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Preface 



The Amiga is the first of a new wave of small computers. This machine 
combines the convenience of a personal computer with the kind of perfor- 
mance that has, until now, been found only on larger systems. 

The Amiga is an easy machine to program, particularly in light of its 
power. However, its flexibility presents the software developer with a great 
many subsystems, details, and options. 

In this book we will explore each of the major subsystems through 
concrete examples. Each example is meant to demonstrate a particular fea- 
ture or detail of the machine and its operating environment. These example 
programs can then form the core of a Library of functions to allow access to 
the Amiga's system services. 

Some of the topics we will cover include: 

• Access to the Amiga's three operating systems— Intuition, 
AmigaDOS, and the executive kernel— using the language C 

• Creation and manipulation of windows, screens, gadgets, menus and 
other Intuition objects 

• Multiprocessing under AmigaDOS, including ports and messages for 
communication between processes 

• Amiga's powerful graphics capabilities for line drawing, area fill, 
polygon drawing, and text fonts 

• Animation with hardware sprites 

• Sound programming in both monaural and stereo, through the audio 
device 

• Speech synthesis and the narrator device 

• File management with AmigaDOS 

The Amiga is an ideal environment for the programmer. Access to the 
system is through the C programming language, and all of our examples are 
in this language. Furthermore, the Amiga software environment is more like 
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I the background while editing another file. You can search a database at the 
! 1 same time as you create a document. You can even send a long output to the 
1 printer and perform other tasks while the printer is executing. 

But beyond questions of productivity and convenience, multiprocessing 
j affects the way you design applications. For example: 

1. A database program might perform long searches as a coprocess with 
its interactive query language interpreter. 

2. A text formatting program could process a file at the same time it 
accepts input from a user. 

Tiese simple examples help to illustrate the differences that program- 
| ming under this kind of ervironment makes possible. You are not, however, 
forced to program in any particular way on the Amiga especially when no 
effort has been expended to enforce a common interface. You do no even have 
to take advantage of the system's multiprocessing capabilities, but can write 
I perfectly acceptable programs in the old-fashioned way-one application in 
memory at a time. Of course, even then you are using multiprocessing^)* 
cause the system programs run in the background. ^ 

I t 
. he Hardware Architecture 

j The hardware architecture of the Amiga is unique! Common among small com- 
puter systems is the traditional single central processing unit (CPU), which 
controls all activities of the machine. Input and output, memory management, 
and the disk drive interface-all must go through this single processor The 
I Amiga in contrast, has a powerful CPU-the Motorola MC68000-but it also 
has a coordinated group of coprocessors and other support circuits to handle 
more specialized tasks. Not everything is handled by the mam processor. 
These specialized devices include: 
. The copper, another general purpose processor that controls the 
graphics system 

. Eight sprite processors that control the movement of these graphics 

objects in the display field 
. The blitter, a device specialized to both move and combine data from 
one part of memory to the other 

In addition to these processors, there are a number of support circuits 
that perform tasks in tandem with the main CPU. 

. The audio system consists of four digital to analog converters that 

give the user maximum versatility in creating sounds. 
. Thirty-two color registers are provided, each of which can be assigned 
any of 4096 possible colors. 

The design philosophy of the Amiga has been to specialize the hardware 
wherever feasible, trusting that this will produce the most efficient design. 
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The organization of these support processors and circuits adds to their 
efficient operation. The Amiga is a bus-oriented system. Each coprocessor, 
each support circuit is on the bus. Most have independent access to the main 
memory through the bus— they are DMA (Direct Memory Access) driven. 
Furthermore, the system clock is arranged so that every other cycle is given 
to these specialized chips. The speed differential between the main CPU and 
the memory is such that, even accessing the bus only every other cycle, the 
CPU is running at full clock speed. Thus, true parallel operation occurs most 
of the time on the Amiga. 

This DMA organization follows through to device drivers. The disk 
drive can transfer data directly between memory and a floppy diskette. There 
is no need to go first through the CPU. The input/output system is similarly 
arranged. This kind of organization is another feature found previously only 
on large computers. There are some restrictions on the DMA subsystem. The 
Amiga is capable of addressing up to eight megabytes of memory directly, 
but only the first 512 kilobytes are available to the specialized hardware. 

The Software Architecture 

The Amiga is really a software driven machine. There are no absolute mem- 
ory locations or hardware addresses where certain key values are stored. 
System services are not accessed by changing memory locations. Since this is 
a multiprocessing system, we can never guarantee the absolute location of 
even key system software. Everything must be specified relative to the loca- 
tion of some anchor value in memory. Access to system routines is almost 
solely through software. 

As mentioned earlier, the Amiga operating environment really consists 
of three cooperating but disparate operating environment: 

1. The executive kernel is the most basic; it is minimal operating system 
supporting memory allocation, communication between processes and 
devices, low-level multitasking, and the primary input/output 
functions. 

2. AmigaDOS is a traditional operating system, responsible for the file 
management system and high-level multiprocessing support. 

3. Intuition is the icon-oriented, window-based system that is the 
primary interface for users. 

Most executive kernel calls are beyond the scope of this book. A chapter 
is devoted to both AmigaDOS and Intuition. 

The executive, as the lowest level, supports both of the other two compo- 
nents. The relationship between AmigaDOS and Intuition, however, is not as 
straightforward. This will be discussed again later in the book; a brief sum- 
mary is all that can be given here. AmigaDOS is the next most basic operat- 
ing system, supplying user-accessible services, particularly those related to 
the file system (e.g., directory displays and file manipulation commands). 
Intuition depends upon AmigaDOS to supply it with a file system; therefore. 



in this sense it is dependent upon AmigaDOS. However, there is not a clean 
Sertchy. Intuition also takes services directly from the execute, mdepend- 
ent of any other subsystem. In practice, this comphcated situation is not a 
problem for either the software developer or the user. 

The programmer can easily move through all three levels of the operat- 
ing system environment and use services from each one in an application 
They are not mutually exclusive. This capability allows powerful software to 
be easily and quickly designed. If a particular system routine is not effective 
ft can be rewritten in terms of lower-level modules, without rewriting the 
entire application on a basic level. Machine level is accessed only when neces- 
sary and then only to the extent that is necessary. 

Access to the System Software 

The Amiga continues a modern trend in systems P r0 8 ramm ^^ t ^ , g 
assemblers are available for the MC68000 microprocessor and k 
configuration in the Amiga, the primary means of programming is through 
the high-level language C. There are many advantages to system program- 
n7ng in C. There fs the great increase in productivity that always accompa- 
nies a move away from a machine specific programming language-each^gh- 
level statement represents more than one machine ^truction. On the Amiga, 
using C helps the programmer deal more adequately with the inherent com- 
11 IX 'Of the macLe" The level of hardware parallelism and the mteractmg 
coprocessor architecture almost require the abstraction offered by a compiled 
language such as C. Since the Amiga is a software dominated system, a 
3s of accessing the system resources is needed. J^ch -portant object, 
whether hardware or software based, has an associated C structure data type^ 
These structures are the programmer's hooks into the machine In some 
cases they allow very low-level access; one structure consists of hardware 
regisVrs for the specfalized chips. Much effort in each chapter will be spent 
describing these data objects. 

The operating system services are accessed by C function caUs. AU three 
environments define their own sets of such functions optimized to their par- 
ticular needs. For example: 

. OpenWindowO creates this Intuition object on the display field. 
. DateO returns values for the system clock maintained by AmigaDOS. 
. WaitO enables the executive kernel to suspend a task while waiting 
for a message at its port. 

These are just examples. In the chapters that follow, we will be incorpo- 
rating many such system functions in example programs. 

You do not lose efficiency in using C. The operating system environment 
presupposes C as the support vehicle for systems progr amming.^ Most of the 
utility programs are written in this language, as well as a Jarge num ber of 
existing applications. As C compilers become more sophisticated and more 
capable of optimizing their output, this situation can only improve. 
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The Organization of the Book 

In this book, we hope to cover the principles and techniques that will allow 
the moderately skilled programmer to write large and mature applications 
taking advantage of the Amiga's powerful hardware and software. We cannot 
cover everything— that would create a truly encyclopedic work. We have tried 
to give the programmer insights into the Amiga's major subsystems and also 
a feeling for its design philosophy. After finishing the book, you should be in a 
- position to deal with the Amiga and to discover even more of its secrets. 

Each chapter in the book focuses on a particular subsystem. The basic 
objects and functions that define and manipulate that subsystem are 
explored. 

Chapter 2 considers the programming environment offered under the 
three operating systems and discusses some of the peculiarities of 
using C on the Amiga. 

Chapter 3 takes a long look at Intuition. It shows how to define 
windows and screens, and explores the notions of gadgets and menus. 

Chapter 4 is devoted to multiprocessing under AmigaDOS, defining 
the notion of a process and explaining how to manipulate it under 
this operating system. 

Chapter 5 explores the graphics capability of the Amiga, showing how 
to access the hardware support routines for such things as area fill 
and polygon drawing. 

Chapter 6 concentrates on the hardware sprites. These are small 
graphics objects that can be moved independently of the rest of the 
Amiga graphics display systen. 

Chapter 7 gives access to the audio channels through the audio 
device. Programming in both monaural and stereo is covered and the 
flexibility of this device is revealed. 

Chapter 8 teaches how to make the Amiga talk. Access to the two- 
part speech synthesizer is covered. 

Chapter 9 returns to AmigaDOS to discuss the file management 
system. 

Each chapter focuses on the essential set of structures and functions 
that will allow the programmer to use that subsystem to create useful de- 
signs. 

It is assumed that the reader is familiar with the C programming lan- 
guage. No tutorial efforts are offered in this book, but example programs, for 
the most part, avoid the more obscure aspects of the syntax. This is not 
through any prejudice for or against a particular programming style. The 
example programs have one goal and that is to illustrate particular aspects of 
the Amiga. While the example programs tend to be simple and straightfor- 
ward, there is no presumption or argument that production code need follow 
this rule. 
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The examples in the text are to be used as guides; each has been de- 
signed recent a particular subsystem of the Amiga u^aUy asug 
feature These programs should be studied and duplicated, but above all, they 
Cld sirve'as'a springboard for more complex software It :» , a « tha 
the only way to learn programming is to program, and it is doubly true on tne 
AmS S program should serve as the basis for a series of experiments 
t££l wfth 5St known to work and having as a goal some personal 
£S OftenThese programs can be easily merged to produce a more com- 
plex example. 



Note About the Example Programs 

The main thrust of the programming examples throughout the text u , to 
must^ate the methods by which each Amiga ^^VZ^iT^Z 
rrnlled In every case, the clear expression of ideas is the first priority, inebe 
£££ Z often be improved by the addition of expKat -or^ecbng 
and the use of more efficient programming constructions but at the cost of 
more complicated and difficult to follow algorithm pvnprtise of the 

An important but secondary consideration is the level of expertise of the 
reade WMe not an explicit tutorial in C, an expert's knowledge of tins 
programming language is' not required. Most of the ob-c^^tructomjm 
this language have been avoided-sometimes at a loss m efficiency. This book 
L deseed to serve the individual who is just learning to program in C as 
well as the more experienced programmer. 

1 complete program should be efficient and contain explicit error check 
ins This ; SpartiSy true in the case of a multitasking environment such 
Ste A^* w Smany programs competing for limited resources such as 
me^ The reader should be careful to include these considerate m the 

run ob af Amiga system with 512 kilobytes of memory. This is 
can be directly accessed by the specialized coprocessors; caUed chip memory 
Tmust b^tinguished from any additional -P^^^haXS 
latter can be used by any C program but not by the specialized h ^ dwa J v 
Carl - be taken when creating variables or allocating memory ^hat only 
chip memory be used for graphics or other specialized subsystems. There are 
£ pubTic domain programs that will correct existing programs that do not 
perform properly in expanded systems. 
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Figure 2-1. Traditional methods of accessing 
hardware resources 
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fort* Differences are represented by new interpretations of individual com- 
mands and bypassing different values to an object. A write command to a 
wffl £t something on a disk, while the same write command to an 
audio channel will result in the production of a sound (Figure 2-2). This 
coSLtenH.terface increases flexibility in another dimension: redirecting 
output from one device to the other is greatly simplified. 

To create this shield, the Amiga has a multilayered operating system. 
Each layer performs its own set of duties, presupposing the services of lower- 
feve Wtions3 supplying the necessary objects for higher-level ones 
Sever, it must be emphasized that this is not a^rong hierarchy as^ 
commonly found in multitasking operating systems. The programmer^ is free 
Se any level of the Amiga's software environment and even, with some 

reasonable restrictions, to mix levels. onv ; r<ln - 
The three main components of the Amiga's operating system environ 

ment are: 

1. The executive kernel 

2. AmigaDOS 

3. Intuition 

These represent not only three different ^^J^"^^^ f 
software designer, but also different philosophies of design. F^thermore^ 
eadThas its strengths and weaknesses. Intuition is the f 
system for the Amiga. This is the one designed for the user of sof war^It is a | 
visual interface with windows and pop-down menus, all controlled by aj 
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Figure 2-2. Commands will have different interpretations when 
applied to different devices 



PUTS A NEW 
TRACK ON THE 
DISK DRIVE. 





CAUSES THE 
AUDIO DEVICE 
TO PRODUCE A 
SOUND. 
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mouse. Its name describes the philosophy of its design: it is meant to be an 
intuitive command shell. A user should be able to access the Amiga through 
Intuition with only minimal outside instruction. For the programmer, Intu- 
ition is the most complex of the three operating systems to deal with. 

AmigaDOS is a more traditional operating system. Organized around a 
command line interpreter that is reminiscent of the UNIX shell, this will 
seem more familiar to the experienced programmer. Two important subsys- 
tems are defined in this operating environment: 

1. The file management system 

2. The high-level multitasking system 

Both of these topics need further elaboration and, in fact, a chapter is 
devoted to each. Suffice it to say here that things such as the directory and 
format for each kind of file are defined as a part of the AmigaDOS operating 
system. The notion of a process and the loading and unloading of software 
segments are integral parts of this DOS environment. Most software develop- 
ment is done in this familiar environment. 

At the lowest level of the Amiga's software architecture is the executive 
kernel, the most basic operating system. In fact, the other two operating 
systems— Intuition and AmigaDOS— rest upon it (Figure 2-3). The two pri- 
mary duties of this subsystem are: 

1. To provide a message sending system to support multitasking 

2. To handle low-level, device-specific input and output 

In many operating systems, this level would be unavailable to the pro- 
grammer, but with the Amiga it is not only available, but access to it has 
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Figure 2-4. Compiler as a production engine 




library 




file 





<l> 

1 p* 



^ TU choice of . « -j^i-S- JStSSt - fF 
their operation. 



Lattice C 

The Lattice compiler is divided into w v 
invoked separately through its own command hne. 
L LCI starts the first phase of the compile. 
9 LC2 begins the second phase. 

are: 

. Preprocessor command execution 

aBS an object file ^SS.-*- 1 "'"""'^ 
object file contams a mixture oi mdc 

Mt tr£5 jr-n* » — » th • mique co ° ma " <1 

For the first stage, the format is: . 

,., ,.„.inc. file name 
U1 >Listing_fUe toggles 
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where 

listing_file names a disk file that will accept all messages including 
messages that would ordinarily be sent to the screen. This is an 
optional part of the command line and must be a fully qualified file. 
No default values are defined. 

toggles represents a list of compiler toggles that control the action of 
the compiler and can change some default values. This too is an 
optional part of the compiler command line. 

file _ name indicates the source code file. Note it need not end in .c but 
if no extension is explicitly mentioned, this will be assumed. 

The only requirement for starting a compile is that the source file name 
must be given, although optional arguments to the command hne may help in 
the development process. 

A complete list of the compiler toggles for the first phase of compilation 
is shown below. Among the more commonly used ones, we find: 

-d puts debugging hooks into the intermediate quad file. These can 

then be used later by an optional debugging program. 

-dname is equivalent to a Kdefine statement in the source file. It can 

be used in conjunction with the ttifdef or ttifndef preprocessor 

statements. 

-i forces data elements to be aligned on long word (32-bit) boundaries. 
This alignment is important for compatibility with AmigaDOS 
structures. 

-p produces a file with the extension .p. that contains the source code 
along with the full expansion of the preprocessor statement. No 
executable file is produced. 

-oo_name gives the object file produced by the compiler a name 
different from the source file. 

First pass compile r toggles 

-b this causes all static and external data references 

to go through a base register (A5 or A6) . 

-c<flags> these control compatibility with earlier versions of 

the compiler. Flags may be concatenated with no 
white space between them 

c allows nested comments. 

d $ may be embedded in identifiers. 

m mulitple character constants allowed. 



mxs- 



generates only a single copy of identical string 
constants . 
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forC es character declarations to be unsigned. 
no earning for return statements not specifying a 
value. 

puts debugging information in the object file. 

-d<nam e > equivalent to define <name>. 

- d <nan,>=<value> equivalent to define <name> <value> 

except those atreauy v specified in 

period. Up to four such names may oe *v 
separate -i clauses. 

all data items except short and char -ill be long 
yord aligned. 

tru ncates identifiers from 32 to 8 characters, 
causes the quad me to be called <name>. 

i -i * n be produced that 

No quad file is produced. 



automatic symbol definitions are cancelled. 
the storage class for externals is changed from 
external definition to external 



i a ,„«t as thev have been represented here. 
Compiler toggles are invoked just , as they n leitoco mpne 

prefaced by a hyphen and ^^"^Zj, and to make sure that 
T^t^C W — s, the followhig command hne 

would be used: 

LC1 >df1:err_list -oobj "l src.c. 

u ivpn the full ffle name for the list file. The second 
Note that we have given the run iue . . 

phase of compdation has a similar command format. 

LC2 toggles filename 

Hereme-namerefer^af^ , 
phase of the » A-*- - J - Qbject produced by J 

* ^ ^r.. This restrict^ 
, ma kes aU addressing Agister, but is necessary to 
the addressing range to 64K arauna 
produce position independent code. 
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A complete listing of the second stage compiler toggles is shown below. 

Second pass compiler toggles 



-fn specifies register A5 (n=5) or A6 Cn=6> as the stack frame 

pointer. 

-o<name> changes the name of the output file to <name>. 

- P causes the addressing to be PC relative; this limits 

addressing range to 132k. This is used for creating 

position independent code. 



Invocation of this stage is similar to that of LCI. 
LC2 -oobj src 

This command creates an object file obj.o from the intermediate file 
src.q. Note that there is no option for an error listing file in this second phase 

The compiler will report errors whenever it finds them. A successful 
compiler during the first phase will report nothing back to the screen. How- 
ever, at the end of the second phase, the size of the resulting code will be 
displayed to the user in the form: 

Module size P=9999 D=9999 U=9999 
where 

P indicates the size of the executable code segment. 
D is the size of the initialized data module. 
XJ reports on the uninitialized data area. 

All measurements are in bytes and are written in hexadecimal. 
Lattice C contains a compiler driver or shell that will automatically 
invoke both phases of the compiler. It takes the general form: 

LC toggles f i le_name1 f i le_name2 . . . 

Each file name must be separated from the others by white space. 

The toggles list is created by a mixture of options from either phase as 
well as two toggles peculiar to this command line form. Only one argument is 
ambiguous: -oo_name. This ambiguity can be resolved by using -qx in place 
of -o. This form can also be used to change the default location for the quad 
ML file-it is automatically put in the RAM disk (RAM:). The -v command op- 
tions make Lattice C verbose, displaying each line as it is executed. 

Finally, Lattice C comes with an object modular disassemble, OMD, to 
help in debugging. This utility program provides a list of machine language 
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command file would contain those V^^J^l^t^^ 

important programming aid. 

Contentsof_atypic^^ 



i ;K . i i n k both libraries^ 
LIBRARY ^0:Ub/ua rI 0:U b /a rt .Ub, p ^ ^ 
„ AP dfTssymbolmap.ref «• crQSS refe rence fi It. 
XREF dfV.crossref.ref, also format is 3 sym bols across. 
WIDTH 3; 



n„r, of a map of the executable module 
The MAP parameter allows during the first pass. 

th * will be produced [^^^^oa^^^^ 
This link map contams a hstmg tor 

of: . • •„ n f rhe segment (truncated to eight 

. The file name that was the origin of the segm 

characters) 
. The segment reference number 
.^hetypTof the segment-data, code, etc. 

• The size , m« in the segment, along with 

In addition to this •** »'"«^ foti ° e " 

shown m Listing 6x. . , ., TNK 

U^ij^MJ^^^ 

Hunkname: text 

File: LIB-.LStartup.obj 
Program Unit: No Nam « 
Base: 000000 Size: 0001 CC 

Value 

Symbol 

000001 3 A 

XCEXIT 



Hunkname: data 

File- LIB:LStartUp.obj 
Program Unit: No Name 
Base: 000000 Size: 00005C 



Symbol 



Value 
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Listing 2-1. (cont.) 



Mill 1 


00000000 


base 


00000004 


mud & c 


00000008 


__mnext 


oooooooc 

UUUUUUU V* 


msi ze 


00000010 


mstep 


00000014 


tsi ze 


00000018 


oserr 


0000001c 


f perr 


00000020 


_console_dev 


00000028 


_SysBase 


0000002C 


_0OSBase 


00000030 


"LoadAddress 


00000034 


_WBenchMsg 


00000038 


~_StackPtr 


0000003 C 


ProgramName 


0000004C 



XREF produces a cross-reference table containing a listing for each 
symbol in the file and a list of references for that symbol. Each reference 
consists of a code segment number and an offset value into that segment. 
This linker option uses the same header format as the MAP. This is illus- 
trated in Listmg 2-2. 

The WIDTH parameter specifies the output format for the MAP and 
XREF tables. It indicates the number of symbols printed per line. The de- 
fault is a single symbol per line. 

Listing 2-2. A partial listing compiled by the XREF option to ALINK. 



0. CODE. Memory Type PUBLIC Total Size 0001 CC. 
Hunkname: text 

File: LIB:LStartUp.obj 
Program Unit: No Name 
Base: 000000 Size: 0001 CC 

Symbol Offset Hunk Offset Hunk Offset Hunk 



.XCEXIT 



00000058 56 



1. DATA. Memory Type PUBLIC Total Size 00005C. 
^Hunkname: data 
F 'le: LIB:LStartUp.obj 
Program Unit: No Name 

000000 Size: 00005 C 
01 Offset Hunk Offset Hunk Offset Hunk 



•se 
.■base 
-■next 



00000006 2 
00000090 41 
00000096 41 
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0000008A 


41 










msize 


0O00O0BC 


44 


UUUUUUt L 


44 






~~mstep 








35 


000002 FA 


35 


"tsi ze 


000001 DO 


35 


000002 fo 




0000044A 


35 


__oserr 


0000036E 


35 


UUuuutut. 


35 








00000008 


70 






000004C8 


35 


fperr 


00000478 


35 




35 


00000582 


35 


"^onsole.dev 


00000522 


35 




35 
35 


000005 F6 


35 




00000598 


35 


OOOOUbDo 




00000034 


84 




00000004 


84 


0000001 C 


84 
84 






SysBase 


00000048 


OH 


00000060 


83 


0000003 C 






oooooooc 


83 


00000024 




0000007 C 




_0OSBase 


00000058 


83 


0000006C 


83 


OOO0OOC4 






00000094 


83 


000000AC 


83 




X A 




00000008 


83 






















LoadAddress 


000001 4A 


76 








~WBenchHsg 


00000002 


75 










~_StackPtr 
ProgramName 


00000018 


79 
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is start-up code and must come at the beginning of the program. This file 
must be the first one read and transferred to the output. Following are some 
typical ALINK command lines. 

Typical ALINK Command lines 

Simple link: 

ALINK FROM LStartUp.obj+df1 :demo.o TO df1:demo LIBRARY lib/lc.lib+ 
lib/amiga. lib 

f^~\ " Full link: 

ALINK FROM LStartUp.obj+df1 :demo.o TO df1:demo VER message LIBRARY 
lib/lc.lib+lib/amiga.lib MAP df1 : symbol. ref XREF df1:xref.ref 

^ ^ Link using a WITH file: 

ALINK FROM LStartUp.obj+df1 :demo WITH df1 commands 

Link for AmigaDOS: 

ALINK FROM AStartUp.obj+df1 :demo.o TO df1:demo LIBRARY 
lib/amiga. lib 



Specialized Amiga Data Types 

Access to the Amiga's system resource is supplied through software objects 
defined in terms of C syntax rules. The system also supplies a set of special- 
ized data types to ease the programmers plight and to enhance internal 
documentation. It must be emphasized that these are not really new types at 
all, but merely a renaming of data types standard to C. The new names help 
relate these types to the realities of the Amiga environment. For example, 
although type BOOL is really just a short integer, the word BOOL conveys 
that this value is a boolean, better than the more ordinary short designator. 
The advantage is really one of suggestion, but in a long and complex pro- 
gram, this can be quite valuable. 

The creation of these new names is done with the typedef statement. The 
example type BOOL is created with the statement: 

typedef short BOOL; 

This is a form long familiar to C programmers. Of course, this has no 
effect on the data type short; it only alerts the system to the fact that there 
are now two distinct ways to declare a variable of this type. 

The complete list of these special types can be found in Table 2-1. 
Among the more important and commonly used, we find: 

LONG long 

ULONG unsigned long 

25 
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WORD short 
BYTE char 

UBYTE unsigned char program and the 

Either form of these data ^types can be used ta the 

system wiU understand it. They may 

sane file. 



Table 2-1. Amiga data types 



1 


auic * ° 

c . „j or( i c Tvpes 




Amiga Types . 


long 




LONG 


unsigned long 




ULONG 


unsigned long 




LONGBITS 


short 




WORD 


unsigned short 




UWORD 


unsigned short 




WORDBITS 


char 




BYTE 


unsigned char 




UBYTE 


unsigned char 




BYTEBITS 


♦unsigned char 


STRPTR 


♦unsigned char 


APTR 


short 




SHORT 


unsigned short 


USHORT 


float 




FLOAT 


double 


DOUBLE 


short 


COUNT 


unsigned short 




UCOUNT 


short 




BOOL 
TEXT 


unsigned char i 





One final note involves the 5S?Eg 
on the Amiga. The C *^££?J?Z with any absolute value- 
unit of storage-the computer word ^ lementati on-dependent; therefore^ 
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Table 2-2. 1 


Data element s 

Bit Size 


izes for Lattice ^ »" ; — _ 

Range of Values . 


"j $8 


Data Type 


8 


-128 to +127 




char 


8 


0 to 255 




unsigned char 


16 


-32768 to 32767 




short 


16 


0 _ t 2 O 1 6 4 5 5 4 3 8 5 3,648 to 2,147,483,647 




unsigned short 








int 


32 
32 


0 to 4,294,967,295 




unsigned int 


32 


same as int 




long 




same as unsigned ffit 




unsigned long 


32 
32 


+ 10E-37 to +10E38 




float 

double 


64 


+ 10E-307 to ±10E308 
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Summary 

This chapter has discussed the Amiga progranirning environment. It has 
explored the way in which this system offers access to the hardware resources 
and software subsystems of the Amiga. It has also discussed some of the 
problems and benefits of a multiprocessing computer system. 

The basic operation of the compiler and the linker has been covered. You 
have seen their basic operation and some of the important options that they 
offer. The system's debugging facilities have been touched upon, including: 

The OMD (Object Module Disassembler) 
The MAP option to ALINK 
The XREF option 

Examples have shown how these might help a programmer quickly 
diagnose and repair software problems. 

Finally, this chapter has discussed the specialized data types defined 
with the Amiga's software system, and you have seen how they might be used 
to enhance the internal structure of a program. 
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Intuition is the window-based interface most often used to access the 
Amiga. It serves as a standard interface within which input and output 
can be conveniently generated and controlled. The resources available include 
screens, windows, menus, and user-manipulable icons called gadgets. In this 
chapter, we will discuss methods for generating these objects and interfacing 
them to user created programs. 



Intuition 





The basic philosophy of Intuition is well indicated by its name. It is meant to 
be an interface that offers the full range of operating system services yet 
requires the minim um amount of off-line study to master. Every aspect of the 
computer is meant to be transparent and obvious to the user. The main access 
channel is the mouse, although it could be any similar device, such as a 
joystick. These devices are typically used for pointing. Access is reduced to as 
few actions as possible. 

Intuition is a world of screens and windows. The screen is the main 
visual object; within it certain key parameters such as font, color, and resolu- 
tion are set. The window is the locus of most activity in Intuition. It handles 
input and output and contains the gadgets— specialized control objects. Both 
windows and screens can be freely moved around within limits set by the 
programmer. 

The ease with which a user can manipulate the objects in Intuition, 
however, is not carried over to program writing. Of the three programming 
environments found on the Amiga— Intuition, AmigaDOS and the execu- 
tive kernel— this is the most difficult one in which to develop software. 
Intuition is a very complex system which requires even small, simple pro- 
grams to handle many display details. However, Intuition is and is meant to 
he the primary user operating system, and successful software will have to 
•leal with it. 
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one process at a time, although only one window can be active for input at any 
given moment. Moreover, each process has sole control of its console device, 
so no special consideration need be given to coordinating the output of dispa- 
rate programs. Because of their importance, the creation and manipulation of 
windows within Intuition is an optimized procedure. 

A screen is a somewhat more limited structure. It is the background 
upon which windows are displayed and manipulated. Like the window, the 
screen shows a rectangular figure on the display. This does not mean that a 
screen definition is only a specification for a background display— a few 
colors and maybe a style of lettering. The screen contains the window not 
only in the sense of framing its display, but in the more profound sense of 
containing all of the structures and values that the window itself manipu- 
lates. It is both a tangible limit and a system work area for the windows. 

There are two kinds of screens available under Intuition. The standard is 
the Workbench Screen; this is predefined and needs no specification or action 
on the part of an application to open or close. But Intuition also allows the 
option of creating a customized screen specialized to a particular program or 
set of programs. In the latter case, the screen must be specified; its values 
must be initialized; and it must be explicitly opened before any windows can 
make use of its capabilities. The Workbench Screen is the one you are already 
familiar with: it covers the entire display area and contains the familiar 
capabilities. A customized screen can be any size, within the limits set by 
Intuition, and can contain either a subset or superset of the features found in 
the Workbench Screen. The chief advantage of the Workbench Screen is that 
it offers a standard interface to the user— one that is the same over a variety 
of applications. Also, it runs in concert with the Workbench application and 
has available to it specialized characteristics, such as icons, which may not be 
easy to import to a customized screen. Figure 3-1 shows a typical Workbench 
Screen; Figure 3-2, a customized one. 

A screen allocation not only creates the display that you see, but also 
sets aside a workspace within memory where you can define your windows. 
Each window requires not only a set of data objects to manage its changing 
values, but also space to perform its calculations and an area to draw any 
necessary graphics. In addition to this, the screen sets certain parameters 
that are inherited by its windows. For example, the screen sets the color 
registers and the default type font. 

Even though a screen is a basic element in an Intuition display, there is 
not a single basic screen underlying all others. There can be as many screens 
nnining as is desired and can be supported by the memory resouces of the 
system. Each screen is a world unto itself, as there can be no direct communi- 
cation between them or between their windows. Windows cannot be moved 
^outside of their designated screens. However, screens may overlay one an- 
other either wholly or partially. 

In this chapter you will first explore the definition and manipulation of 
; Windows and screens. You will discover not only how to make them appear, 
'but also how to manipulate their interrelationship to produce displays and 
■Pplications. 
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you to focus on window-specific topics and put aside, for the moment, some of 
the complications generated by customized screens. Additionally, it will pro- 
vide some interesting objects that you can then reimplement in custom 
screens, to explore these complications more fully. 

Two objects are necessary to create a window. These objects are speci- 
fied by a C structure. The New Window structure is used to specify the 
parameters of a window and pass those values to the Intuition function, 
OpenWindowO, which creates the window. This function initializes the sec- 
ond structure associated with an open window, the window structure; this, in 
■ turn, is used to manipulate the window. 

NewWindow is a temporary structure that is only needed until the 
window is up and running. Its memory can then be deallocated or reused to 
open another window. NewWindow is a C structure with the following form: 

struct NewWindow { 

SHORT LeftEdge.TopEdge, 

Width, Height; 
UBYTE Detai IPen, BlockPen; 
USHORT IDCMPFlags; 
ULONG Flags; 

struct Gadget *Fi rstGadget; 
struct Image *CheckMark; 
UBYTE *Title; 

struct Screen *Screen; * > 

struct BitMap *BitMap; 
SHORT MinWidth.MinHeight, 
MaxWidth.MaxHeight; 
USHORT Type; 

>; 

Each one of these fields controls one or more aspects of the window, but 
we will initially restrict ourselves to the minimal subset necessary to display 
a window. 

LeftEdge and TopEdge define the coordinates of the upper left hand 
corner of the window, setting its initial position. 
Width and Height set the size of the displayed window. 
DetailPen and BlockPen contain references to the colors used to draw 
around and within the window; 

Flags contains a series of values that set various capabilities and 
activities. 

Text is the title of the window. 

Type refers to the screen in which the window will be embedded. 

For now, we will set the other fields to NULL or 0 and ignore them. The 
dues assigned to these fields are partially dependent on the characteristics 
of the screen and partially on your own desire. 

The initial position of the window is set in relation to the upper left-hand 
comer of the enclosing screen. This is always position 0,0. The units of these 
measurements are pixels or picture elements, but the size of these pixels is 



Using Intuition 




dependent on the resolution of the will be 640 horizontal 

t be using the Workbench S^^^fwith custom screens, resolu- 
by 200 verticaUy. Later on ^^^Positioning of the window is m 

WBENCHSCREEN. Both the window. DetaiWen 

IXs. These are ^^jtaw thTborders and the deta* jrfto 

S£ SS ^^^^^^ SSs b wf - 
SrSTw. « these fields f « m ^p 0 rtant in the structure. We will use 
Sed^he FUvs field *™ to become active as soon as * 

the ACTIVATE flag, which will cause i tne receive input. 

a opened. This means that it will be the onew^ ^ j. 

Luting 3-1 shows a program Jt^o^ minimal ^ 

Workbench Screen. You will see right away how str g ^ ffl 

5?£3f it to the T«£S^£a«r is controUec 1 by a 

we will increase the complexity ot our ■ » f 5i we wdl have 

TkI fields By the time we discuss grap^ra * example, we 

SS red t Si Power of ^^t°^TtrUcture. We open the 
declare a variable window as aP<"^r oaw ^ mogt mte restmg 

SS» library, then the wmdow and We declare a variab 
action takes place in the ^^^^ the function; this is an aut 
JL Window of type struct ^^"^"L ^ion returns to mam(). Thiaj 
^variable that will f^^^T^ only needed for a caU 
^ not be a problem because th J e can be discarded We set th 

OpenWindowth once this » dj*^^ we want for our window. In ■ 

^^^^ 

in the chapter. 

Workbench Screen. 



S ^K^uUion. h > 

struc t mtuitionBase -mtuitionBase; 
struct Window *Window; 
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Listing 3-1. (cont.) 
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mainO 
LONG i; 
OpenAUO; 

/* ======open a new window===== */ 

make_wi ndowO ; /*error checking could be included* 

/* ======De lay -for a bit to show off the window====== */ 

f or ( i =0 ; i <1 000000 ; i ++) 
CloseWindow(Window) ; 

> 

OpenAUO 

/♦This function will open the necessary libraries */ 
{ 

Intui tionBase=(struct IntuitionBase *) 

OpenLibraryO'intuition. library", INTUITION_REV) ; 

if (Intui tionBase==NULL) 
ex it (FALSE); 

> 

make_window() 

/* This function will initialize the NewWindow structure 
and open the window */ 

{ 

struct NewWindow NewWindow; 

NewWindow. LeftEdge=20; 
NewWindow.TopEdge=20; 
NewWi ndow. Width=300; 
NewWi ndow. Height=1 00; 
NewWindow.Detai lPen=0; 
NewWindow. BlockPen=1 ; 
NewWindow. Title="A Simple Window"; 
NewWi ndow . F lags=SMART_RE FRESH | ACTIVATE | BORDERLESS; 
NewWi ndow. IDCMPF lags=NULL; 
NewWi ndow . Type=WBENCH SCREEN; 
NewWi ndow. Fi rstGadget=NULL; 
NewWi ndow. CheckMark=NULL; 
. NewWindow. Screen=NULL; 
NewWindow. BitMap=NULL; 
NewWi ndow. Mi nWidth=0; 
NewWindow. MinHeight=0; 
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Listing 3-1. (cont.) 



Nevwindow.MaxWidth=0; 
NevUi ndow . MaxHei ght=0; 

Window=(struct Window *) Openwi ndow(8NewWi ndow) ; 

if(Window==NULL) 
exi t (FALSE) ; 



The call to OpenWindowO is the heart of this function. Note that this 
system routine takes a pointer to the NewWindow structure as a parameter. 
It returns the address of the window structure that will be associated with 
this open window; it allocates the memory for this structure; and it initializes 
the values. If OpenWindowO fails, it returns a value of NULL and the pro- 
gram will exit. 

Once the window has been successfully opened, make _window( ) returns 
control to main(). Here we set up a delay loop so that we may view our 
handiwork, and then we close the window. This closure is accomplished by a 
call to: 

CLosewindow(Window) 

Here Window is also a pointer to a currently open window. It is always 
important on a multiprocessing system such as the Amiga to be careful about 
relinquishing resources when finished with them. Failure to do this can lead 
to deadlock situations, where program execution comes to a halt, because 
memory or some necessary device is not available. 

Certain key operations in this example should be noted; they will be true 
of all subsequent window examples. The basic steps necessary to open a 
window are: 

. Declare a variable to represent the window. This must be a global 
variable of type struct Window. 

• Declare and initialize a NewWindow structure. 

• Call OpenWindow with the NewWindow structure as a parameter. 

• Remember to close the window when it is no longer needed. 

The complexity of the process is really a function of the fields set in 
NewWindow. For this example, we set up the m inimum window. All of the 
fields were set with literal values. In a realistic program, some of these fields 
would be set with variable values. 

The examples in this book, will explore a certain way of approaching 
particular kinds of programming problems. Intuition, in fact, poses several 
difficulties in relation to the kind of stylistic program designs that many 
more orthodox academic or technical programmers are accustomed to. The 
notion of windows and screens and their interaction with an operating system 
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that is more complex than average requires a unique technique. Intuition is 
extremely complex; it requires many variables and data structures even to 
perform the simplest of tasks. The programmer must evolve a way to deal 
with that complexity, or risk writing programs that are unmaintainable and 
undecipherable. What we have attempted to do in these examples is to depend 
heavily on defining C functions for the simple, basic operations and then to 
build the more complex operations out of these modular building blocks. 
Thus, our make_window() function hides the NewWindow structure from the 
main part of the program. If we were to eschew this technique and do every- 
thing in the main function— or any other function, for that matter— we would 
* soon find ourselves with huge and completely unmanageable programs. 

For the moment, ignore those fields in the NewWindow structure that 
have been set to the ubiquitous NULL, concentrating on those fields to which 
an explicit value has been given. The most important of these are: LeftEdge, 
TopEdge, Width, and Height. The first two locate the window on the display 
area. TopEdge specifies the window's vertical offset from the top and 
LeftEdge specifies its horizontal distance from the left-hand side. These two 
dictate where the window will initially appear when it comes into existence. 
Although a full discussion of them will come later in the chapter, these values 
are measured relative to the screen that encloses them. Most of the time, this 
means a measurement is taken from the top and sides of the display, but it is 
possible to define a screen that does not cover the entire area. The Width and 
Height indicate what size box appears. 

DetailPen and BlockPen tell the machine which colors to apply in display- 
ing the window. Depending on the resolution of the display— also a parameter 
that can be set through software— there are sixteen or thirty-two different 
colors available. DetailPen picks the color used to produce the figures and 
border lines in the window, while BlockPen addresses the area fills. In the 
simple example given earlier, we specified the same choices as the screen uses. 

The Title field requires a character string. This string will appear in the 
title bar at the top of the window. In the example, we put a literal string in 
this place. In general, a variable would go here. 

The Type field is used to indicate the kind of screen that will enclose 
the window. Currently, there are only two values possible for this field: 
WBENCHSCREEN and CUSTOMSCREEN. The former is used when using 
the standard Workbench Screen. The latter value is used to create an enclos- 
ing screen to custom specifications. 

Most of the values talked about so far are intuitive. Things such as the 
title, size, and position of a window are all sensible parameters. The Flags field is 
a little different. This field is used to specify a miscellany of important values 
that will shape the display of the window. In the example, there are two such 
values: SMART_REFRESH and BORDERLESS. SMART_REFRESH spec- 
ifies an activity that will make more sense to you after you learn about system 
gadgets (procedures that allow the user to interactively manipulate the window 
and screen). This value indicates to Intuition that it must take responsibility for 
redrawing the window if it is moved or otherwise altered. The BORDERLESS 
flag indicates a display option for the window. By default, windows are drawn as 
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a rectangle with a bar at the top and an outline drawn around the perimeter 
i£Sfl2 f turns off that outline, although it still leaves the bar to chsplay the 
title. The complete list of flag values is shown below. 

Window will become active as soon as it is 
opened. 

Enables the reporting mechanism that alerts 
program when its window is active. 
Creates a window that remains behind all other 
windows. 

Specifies no borders when drawing the window. 
Enables reporting on the Inactive condition. 
Indicates that the window need not be 
refreshed after a change. 
Enables the mechanism to report on mouse 
movements. 

Indicates that window redraw is the 
responsibility of the application. 
Indicates that window redraw and reformat is 
done automatically. 

Specifies that window will have a separately 
maintained bit map. 
Before continuing let's review what we have covered about creating a 
simple window. A window must have the Mowing information specified. 

• Its location within the screen or display 
. Its display parameters: size and colors 
. The kind of screen in which it is to be displayed 
. Special instructions to the display system, such as the fact that the 
window is to be borderless 

These values are common to all windows. Listing 3-2 shows another win- 
dow d^StioT similar to the initial example. This program also sets the minimal 
values needed to bring a window to visibility. 

Listing 3-2. The creation of overlapping windows in the 

Workbench Screen. 



ACTIVATE 

ACTIVEWINDOW 

BACKDROP 

BORDERLESS 
INACTIVE WINDOW 
NOCAREREFRESH 

REPORTMOUSE 

SIMPLE -REFRESH 

SMART_REFRESH 

SUPER_BITMAP 



^include <exec/types.h> 
^include <intuition/intuition.h> 

struct IntuitionBase *IntuitionBase; 
struct Window *WindO,*Wind1 ,*Wind2; 

#define INTUITION_REV 33 
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Listing 3-2. (cont.) 



mainO 
< 

SHORT x,y; 

UBYTE nameC20]; 

VOID delay_funcO; 

/* ======Open Intuit ion======= */ 

IntuitionBase=(struct IntuitionBase *) 

OpenLi brary ("intuit ion. library", INTUITION_REV) ; 

if (IntuitionBase==NULL) 
exit (FALSE); 

/* ======Open some wi ndows===== */ 

st rcpy (name, "Window 0"); 
x=y=20; 

WindO=(struct Window *)make_window(x,y .name) ; 

strcpy(name, "Window 1"); 
x=y=40; 

Wind1=(struct Window *)make_window(x,y ,name) ; 

strcpy(name, "Window 2"); 
x=y=60; 

Wind2=(struct Window *)make_window(x,y,name) ; 
/* ======oelay for a bit to show off the Wi ndows====== */ 

delay_func(1) ; 

/* =========c Lose down the windows in order========*/ 

CloseWindow(Wind2); 
delay_func(1) ; 

ft 

CloseWindow(Windl); 

delay_func(1); 

CloseWindow(WindO); 

> 



make_window(x,y,name) 
SHORT x,y; 
UBYTE *name; 

/* This function will initialize the NewWindow structure 
and open the window. Add error checking */ 

< 

struct NewWindow NewWindow; 
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Listing 3-2. (cont.) 



NewWindow. LeftEdge=x; 
Ne*Wi ndow . TopEdge=y ; 
NewWi ndow. Width=300, • 
NewWindow.Height=100; 
NewWindow. Detai lPen=-1 ; 
NewWi ndow. BlockPen=-1 ; 
NewWi ndow .Ti t le=name; 
NewWi ndow. F lags=ACTIVATE; 
NewWi ndow . IDCHPF Lags=NULL; 
NewWi ndow.Type=WBENCHSCREEN; 
NewWi ndow. FirstGadget=NULL; 
NewWi ndow. CheckMark=NULL; 
NewWi ndow. Sc reen=NULL; 
NewWi ndow. Bi tMap=NULL; 
NewWindow. MinWidth=0; 
NewWi ndow. Mi nHeight=0; 
NewWi ndow. MaxWidthO ; 
NewWi ndow. MaxHei ght=0; 



return (OpenWi ndow (SNewWi ndow) ) ; 

> 

VOIC delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
{ 

int loop; 

for(loop=0; loop<f ac tor*1000000; loop++) 



return; 

> 



Two new things should be noted about Listing 3-2. Most importantly, it 
opens more than a single window. In fact, it opens three: WindO, Windl, and 
Wind2. Each one of these must be represented by a window structure, and 
each one must be created by a separate call to OpenWindow(). They can, of 
course, share the same NewWindow structure, since it is only used during the 
setup process. Creating multiple windows like this is a common occurrence. 
Note how Intuition automatically takes care of the display problems involved 
with overlapping windows. Also in this example, there are two new values used 
in the NewWindow structure. DetailPen and BlockPen are set to -1. This 
value indicates to Intuition that the screen default values are also to be used 
for the window. We've used the Flag value ACTIVATE to insure that the 
window will become active as soon as it is opened. The lack of a 
BORDERLESS value for this field results in the appearance of the windows 
neatly delineated by a clean, white border. 



Z E R O 

ZARAGGZA 
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Listing 3-3 shows one of the uses of a borderless window: it can serve as 
a backdrop for the activity of other windows. In this program, we first open a 
window specifying the BORDERLESS flag and covering the entire display 
area— 640 by 200. Once this underlying window is in place, we open three 
ordinary windows that appear in front of it. This is a useful technique for 
creating a clean and pleasant display. It will be used to good effect during 
graphics programming in Chapter 5. 

Listing 3-3. Creation of overlapping windows in the Workbench 
Screen with a borderless window in the background. 



^include <exec/types . h> 

#inc lude <intuition/intui tion.h> 

struct Intui tionBase *IntuitionBase; 

struct Window *Wind0,*Wind1 ,*Wind2,*NoBorder; 

tfdefine INTUITION REV 33 



mai nO 
{ 

ULONG flags; 

SHORT x,y,w,h; 

UBYTE nameC60]; 

VOID delay_func() ; 

/* ======0pen Intui tion======= */ 

IntuitionBase=(struct IntuitionBase *) 

OpenLibrary ("intuit ion. library", INTUITION_REV) ; 

if (Intui tionBase==NULL) 
exit (FALSE); 

/* ======0pen a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

f Lags=ACTIVATE | BORDERLESS; 

NoBorder=(struct Window *)make_window(x,y,w r h,NULL,f lags) ; 



/* ======0pen some plain windows===== */ 

strcpy(name, "Window 0") ; 

x=y=20; 

w=300; 

h=100; 

f lags=ACTIVATE; 

WindO=(struct Window *)make_window(x, y.w.h, name, f lags) ; 

strcpy(name, "Window 1"); 
x=y=40; 
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Listing 3-3. (cont.) 



Wind1 = (struct Window *)make_window (x ,y,w,h .name, f lags) ; 

strcpy(name, "Window 2"); 
x =y=60; 

Wind2=(struct Window *)make_window(x, y.w.h, name, f lags) ; 
/* ======oelay for a bit to show off the windows====== */ 

delay_func(100); 

/* =========c Lose down the windows in order========*/ 

CloseWindow<Wind2); 
delay_func(10); 
CloseWindow(Windl); 
delay_func(10) ; 
CLoseWindow(WindO); 
delay_func(10) ; 
CloseWindow(NoBorder) ; 

> 



make_wi ndow (x.y.w.h, name, flags) 
SHORT x.y.w.h; 
KBYTE *name; 
ULOHG flags; 

/* This function will initialize the NewWindow structure 
and open the window. Error checking should be added */ 

struct NewWindow NewWindow; 

NewWindow. LeftEdge=x; 
NewWi ndow. TopEdge=y, ■ 
NewWindow.Width=w; 
NewWindow. Height=h; 
NewWi ndow. Det a i lPen=-1; 
NewWindow. BlockPen=-1 ; 
NewWindow. Title=name; 
NewWindow. Flags=f lags; 
NewWi ndow. IDCMPF lags=NULL; 
NewWindow. Type=WBENCHSCREEN; 
NewWi ndow. FirstGadget=NULL; 
NewWindow.CheckMark=NULL; 
NewWi ndow . Screen=NULL; 
NewWindow. BitMap=NULL; 
NewWindow. MinWidth=0; 
NewWindow. MinHeight=0; 
NewWindow. MaxWidth=0; 
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Listing 3-3. (cont.) 

NewWi ndow. MaxHeightO ; 

return (OpenWi ndow (SNewWi ndow) ) ; 

> 

VOID delay_func(factor) 
, int factor; 

/* This function will cause a specified delay */ 

int loop; 

for(loop=0; loop<f actor*1000; loop++) 
return; 

> 



Listing 3-4 shows a variation of the previous examples. The situation is 
the same, but each window in the foreground of the display is a different 
color. This is accomplished by specifying a different color register for the two 
color members in the NewWindow structure: DetailPen and BlockPen. The 
number of colors available is a function of the screen. In the case of the 
Workbench Screen, there are four. 

Listing 3-4. Creation of overlapping windows in the Workbench 
Screen, with a borderless window in the background. In this 
program, we specify different colors for the small windows. 



^include <exec/types.h> 

#inc lude <intui t ion/ intuit ion. h> 



struct IntuitionBase *IntuitionBase; 

struct Window *WindO,*Wind1 ,*Wind2,*NoBorder; 



fldefine INTUITION REV 33 



mainO 
{ 

ULONG flags; 
SHORT x.y.w.h; 
UBYTE *name,c0,c1; 
VOID delay funcO; 



2 E B O 

ZARAGOZA 



/* ======Open intuit ion======= */ 



IntuitionBase=(struct IntuitionBase *) 

OpenLibraryC'intuition. library", INTUITION_REV) ; 



45 



r 



sing /ntuttto" 



Listing 3-4. (cont.) 



if(IntuitionBase==NULL) 
exit (FALSE) ; 



= =====Open a borderless wi ndow======*/ 

x=y=0; 
«=640; 
h=200^ 

SSSSSvi™ I borderless; 

NoBcrder=(struct : Window J> fLagSfCU|C l> ; 
make_windowCx,y ,w. n »" u 

== ====Open some plain windows===== */ _ 

won 



name="Window 0"; 
x=y=20; 
w=300; 
h=100; 

flags=ACTIVATE; 

c 0=0x10; 
c1=0x15; 



[AT 



name ="Window 1 ; 
x=y=40; 
C 0=0x17; 

C1= ° X19: nH OU (x y w,h, name. flags. cO.cD; 

wi nd1 = (struct Window ♦Omake.wmdowCx.y 

name="Window 2"; 

x=y=60; 
C 0=0x00; 

delay funcdOO); ^ 
„ ==== =====Close down the windows in order==== 

CloseWindow(Wind2) ; 

delay _func(10>; 
CloseUindowCUindD; 

delay_func(10); 
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Listing 3-4. (cont.) 

CloseWindow(WindO) ; 
delay_func(10) ; 
CloseWi ndow(NoBorder) ; 



make_window(x,y ,w,h, name, flags, co lorO, co lorl ) 

SHORT x.y.w.h; 

UBYTE *name,color0,color1 ; 

ULONG flags; 

/* This function will initialize the NewWindow structure 
and open the window. Error checking should be added */ 

{ 

struct NewWindow NewWindow; 

NewWindow. LeftEdge=x; 
NewWi ndow . TopEdge=y ; 
NewWi ndow.Width=w; 
NewWi ndow. Heigh t=h; 
NewWindow. Detai lPen=colorO; 
NewWindow. BlockPen=color1 ; 
NewWi ndow. Tit le=name; 
NewWi ndow. F lags=f lags ; 
NewWi ndow. I DCMPF lags=NULL; 
NewWi ndow. Type=WBENCHSCREEN; 
NewWindow. Fi rstGadget=NULL; 
NewWi ndow. CheckMark=NULL; 
NewWi ndow. Screen=NULL; 
NewWi ndow. Bi tMap=NULL; 
NewWi ndow. Mi nWidth=0; 
NewWi ndow. Mi nHei ght=0; 
NewWi ndow. MaxWidt h=0; 
NewWi ndow. MaxHeight=0; 




return (OpenWi ndow (SNewWi ndow) ) ; 

> 

VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
int loop; 

for(loop=0; loop<f actor*1000; loop++) 
^return; 
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So far all we have done with windows is to display them. But windows 
are the true workhorses of Intuition. Windows can move, change in size, show 
graphics displays and text, and can take input. But before we go on to 
explore these topics, we must turn our attention to the object that encloses 
windows— the screen. 

Customizing Screens 

Although windows are more versatile than screens and easier to control, there 
is a great deal of power and flexibility packed into the screen definitions. 
Customized screens combined with windows allow the programmer to create 
any user interface that may be desired. 

\ screen is defined in a way analogous to the window. There is a New- 
Screen structure that allows the specification of screen parameters. This 
takes the form: a 



struct NewScreen -C 
LeftEdg 
Height, Depth; 



UBYTE Detai IPen.BlockPen; T £j - 

USHORT ViewModes, _ » Q U ** 

Type: T & K 

struct TextAttr *Font; " 
UBYTE *DefaultTitle; 
struct Gadgets *Gadgets; 
struct BitMap *CustomBi tMap; 

>; 

These fields are filled out with appropriate values, and a pointer to the 
structure is passed to the Intuition function OpenScreenO. This, in turn, 
returns the address of a screen structure which can be used in subsequent 
interactions. A call to CloseScreenf ) removes it from the display. 

Listing 3-5 illustrates the display of a simple window within a custo- 
mized screen. The NewScreen structure is smaller than NewWindow, and 
almost all of its fields are critical and need to be initialized. Only Font, 
Gadgets, and CustomBitMap are optional and set to NULL. The creation of 
this new screen has been exported to a function, make_screenO. As with 
NewWindow, NewScreen need exist only long enough to serve as a parameter 
for OpenScreenO. This function will return a pointer to a screen ^structure 
associated with the now open and resident screen. If the call fails NULL wiU 
be returned and the example program will exit. The function make ^screen! ) 
returns this pointer value. Note that we must cast this value to a pomter to 
type struct Screen back in mainf ). 

Listing 3-5. Creation of a window in a custom screen. 



^include <exec/types.h> 
(Kinclude <intuition/intuition.h> 

struct IntuitionBase *IntuitionBase; 
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Listing 3-5. (cont.) 



struct Window *Window; 
struct Screen *Screen; 

#define INTUITION_REV 33 



ma i n ( ) 
i 

ULONG flags; 
SHORT x,y,w,h,d; 
USHORT mode; 
UBYTE *name,c0,c1; 
VOID delay funcO; 

N 



======Open Intuit ion======= */ ^* 0 



IntuitionBase=(struct IntuitionBase *) *f W HI 

OpenLi brary ("intuit ion. library", INWlTrei*_R#W ; 



if (Intuit ionBase==NULL) 

exi t (FALSE) ; 
/* ======Open a custom screen==== */ 

name="Screen"; 
y=0; — 
w=320; 
h=200; 
d=5; 

c0=0x00; 
c1=0x01; 
mode=NULL; 

Screen=(struct Screen *) 

make_screen(y,w,h t d,c0,c1 .mode, name); 

/* ======Open windows===== */ 

name="Uindow"; 
x=y=20; 
«=100; 
h=100; 

f lags=ACTIVATE; 
c0=-0x01 ; 
c1=-0x01; 

Window=(struct Window *) 

make_wi ndow(x,y,w,h, name, f lags, cO.d .Screen) ; 

/* ======Delay for a bit to show off the windows====== */ 

delay_func(100) ; 

/* =========C lose down the window then the screen========*/ 
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Listing 3-5. (cont.) 

CloseUindow(Window) ; 

delay_func<10) ; 
CLoseScreen(Screen) ; 



make.wi ndow (x.y.w.h, name, f lags, colorO.coloM .screen) 

SHORT x,y,w,h; 

UBYTE *name, colorO, colorl ; 

ULONS flags; 

Struct Screen *screen; 

/* Ttiis function will initialize the NewWindow structure 
and open the window. Error checking should be added */ 

{ 

struct NewWindow NewWindow; 

NewWi ndow . Left Edge=x ; 
NewWindow.TopEdge=y; 
NewWindow. Width=w; 
NewWindow. Height=h; 
NewWindow. Detai lPen=colorO; 
NewWindow. BlockPen=color1 ; 
NewWindow. Tit le=name; 
NewWindow.Flags=f lags; 
NewWindow. IDCMPF lags=NULL; 
NewWi ndow . Type=CUSTOMSCREEN ; 
NewWindow. Fi rstGadget=NULL; 
NewWindow.CheckMark=NULL; 
NewWi ndow. Screen=sc reen; 
NewWi ndow. BitMap=NULL; 
NewWindow. Mi nWidth=0; 
NewWi ndow. Mi nHeight=0 ; 
NewWi ndow. MaxWidthO; 
NewWindow.MaxHeight=0; 




return (OpenWi ndow (SNewWi ndow) ) ; 

} 

make screen (y,w,h,d,colorO, colorl .mode, name) 

SHORT y,w,h,d; 

UBYTE colorO, colorl ,*name; 

USHORT mode; 

{ 

struct NewScreen NewScreen; 



NewScreen. LeftEdgeO; 
NewScreen.TopEdge=y; 
NewScreen. Width=w; 
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Listing 3-5. (cont.) 



NewScreen. He ight=h; 
NewScreen. Depth=d; 
NewScreen. Detai LPen=colorO; 
NewScreen. BlockPen=color1 ; 
NewScreen. Vi ewModes=mode; 
NewScreen.Type=CUSTOMSCREEN; 
NewScreen. Font=NULL; 
NewScreen. Def aultTi t le=name; 
' NewScreen. Gadgets=NULL; 

NewScreen . CustomB i tMap=NULL ; 

ret urn (OpenS c reen (SNewS c reen) ) ; 

> 

VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
< 

int loop; 

for(loop=0; loop<f actor*1000; loop++) 



return; 

> 



LeftEdge and TopEdge are meant to set the position of the screen. A 
screen must take up the full width of the display area. The height can be set. 
The screen can be smaller than the display area. TopEdge indicates upon which 
of the 200 possible lines the top of the screen will start. There is a further 
qualification: if the screen is less than the full height of the display, it must 
occupy the lower half. A small screen always goes from its top to the last 
possible line on the video screen. TopEdge must be coordinated with the Height 
field. If the screen is specified as less than 200 lines high, then TopEdge cannot 
start at the 0,0 point. The example specifies a screen that covers the full display. 

Even though a screen must be as wide as the display, the Width field has 
a use: it must be set to the number of pixels across the screen. In high- 
resolution mode, Width is set to 640, while low-resolution is only 320. This 
field is used in conjunction with the ViewModes field. ViewModes specifies 
the format of the screen display. For the most part, its values deal with 
display resolution. 

HIRES indicates a high-resolution screen (640 x 200). 

INTERLACE indicates 400 line interlace mode. 
SPRITES allows the use of these objects in the window. 
HAM indicates hold-and-modify mode. 

In the example, we are defining a low-resolution screen and have set the 
fields accordingly. 
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The Depth field indicates the number of colors that will be available to 
the screen and its objects. Its value is the number of bit planes allocated for 
the screen. One bit plane will give only two colors; three bit planes will give 
eight colors. Up to five bit planes can be specified. A complete discussion of 
bit planes will be deferred until Chapter 5. Each pixel has a value in each 
plane, and these are combined to give a color register address. The color of an 
individual pixel is indirectly addressed by this mechanism. DetailPen and 
BlockPen contain the specific color registers to be used for these functions. 
Type must be set to CUSTOMSCREEN. DefaultTitle points to a character 
string that contains the name that will appear in the screen's title bar. 

One reason why screen definitions are so important is that the objects 
contained within screens inherit these characteristics. For example, the win- 
dow created by the example is low-resolution, just as the screen is, and uses 
the same default colors. This consistency is absolute. There is no way a high- 
resolution window can be defined in a low-resolution screen. 

Listing 3-6. Creation of a window in a custom screen. This 
time, we have altered the default colors. 



/* ======Open a custom screen==== */ 



name="Screen"; 

y=0; 

w=320; 

h=200; 

d=5; 

c0=0x10; 
d=0x11; 
mode=NULL; 

Screen=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 .mode, name) ; 

/* ======Open windows===== */ 

name="Window"; 
x=/=20; 
w=100; 
h=100; 

f lags=ACTIVATE; 
c0=-0x01 ; 
d=-0x01; 

Window=(struct Window *) 

make_wi ndow(x,y,w,h, name, f lags, cO.d .Screen) ; 



Listing 3-6 shows a slight modification to the last example. Here we've 
altered the default colors but otherwise the program is identical to Listing 
3-5. Listing 3-7 shows a somewhat more interesting variation. Here we open 
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two overlapping screens, each with its own window. Note that we have 
switched to high-resolution mode. Because of this, we adjusted the Width 
field accordingly and set ViewModes to the flag HIRES. Screen 1 is shorter 
than Screen 2. Listing 3-8 shows the same two screens, but this time the 
smaller one is in low- resolution mode. Although all objects within a screen 
must share its resolution, nothing prevents us from mixing screens of differ- 
ent resolutions on the same display. 



Listing 3-7. Creation of two overlapping custom screens, each 
with a window. 



#include <exec/types.h> 
^include <intuition/intuition.h> 



struct IntuitionBase *IntuitionBase; 
struct Window *wind0,*wind1 ; 
struct Screen *ScrnO,*Scrn1 ; 

#define INTUITION REV 33 



mainO 
< 

ULONG flags; 
SHORT x,y,w,h,d; 
USHORT mode; 
UBYTE *name,c0,c1 ; 
VOID delay_func(); 

/* ======Open Intuit ion======= */ 



FORMAT 
2 E H O ' 

2ARAGOZA 



IntuitionBase=(struct IntuitionBase *) 

OpenLi brary ("intuit ion. library", INTUITION_REV), • 

if (Intuit ionBase==NULL> 
exit (FALSE); 

/* ======Open a hi -res custom screen==== */ 



name="Screen 0"; 

y=0; 

w=640; 

h=200; 

d=3; 

cOOxOO; 
c1=0x01; 
mode=HIRES; 



ScrnO=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 .mode, name) ; /* Add error checking */ 

/* =======And a window==============*/ 
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Listing 3-7. (cont.) 



na«ie="Window 0"; 

x=20; 

y=20; 

w=300; 

h=100; 

f lags=ACTI VATE; 
c0=-0x01 ; 
Cl=-0x01 ; 

windO=(struct Window *) 

make_window(x, y,w,h, name, f lags, c0,c1 ,ScrnO) ; /* Add error 
checking */ 

/* ======open another hi-res custom screen==== */ ^^JP>» 

name="Screen 1"; }} C3 

y=50; r? f& * 

w=640; V> *^ - fS 1 h 

d=J; 7. ^ U ' 

cC=0x00; 

d=0x01 ; 

mcde=HIRES; 

Scrn1=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 , mode, name); /* Add error checking */ 

/* =======And a window==============*/ 

name="Window 1"; 

x=20; 

y=20; 

w=300; 

h=100; 

f lags=ACTIVATE; 
cD=-0x01 ; 
c1=-0x01; 

wind1 = (struct Window *) 

make_window(x, y,w,h, name, f lags, c0,c1,Scrn1); /* Add error 
checking */ 

/* ======D e Lay for a bit to show off the window====== */ 

delay_func(100>; 

/* =========cLose down the window then the screen========*/ 

CloseWindow(windl); 
CloseScreen(Scrn1 ) ; 
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Listing 3-7. (cont.) 



delay_func(10); 
CloseWindow(windO) ; 
C loseScreen(ScrnO) ; 

> 



ma ke_w i ndow ( x, y,w,h, name, f lags, col or0,color1 , screen) 

SHORT x,y,w,h; 

UBYTE *name,color0,color1; 

UL0N6 flags; 

struct Screen *screen; 

/* This function will initialize the NewWindow structure 
and open the window. Error checking should be added */ 

{ 

struct NewWindow NewWindow; 

NewWindow. LeftEdge=x; 
NewWi ndow . TopEdge=y ; 
NewWindow.Width=w; 
NewWindow.Height=h; 
NewWindow. Detai LPen=colorO; 
NewWindow. BlockPen=color1 ; 
NewWi ndow.Ti t le=name; 
NewWi ndow . F lags=f lags ; 
NewWi ndow. I DCMPF lags=NULL; 
NewWi ndow. Type=CUSTOMSCREEN; 
NewWi ndow. Fi rstGadget=NULL; 
NewWi ndow. CheckMark=NULL; 
NewWi ndow. Screen=screen; 
NewWi ndow. Bi tMap=NULL; 
NewWi ndow. Mi nWidt h=0; 
NewWi ndow. Mi nHeight=0; 
NewWi ndow. MaxWidth=0; 
NewWi ndow. MaxHei ght=0; 



ret urn(OpenWi ndow (SNewWi ndow) ) ; 

> 

make_screen(y,w,h,d,color0,color1 .mode, name) 

SHORT y,w,h,d; 

UBYTE color0,color1 ,*name; 

USHORT mode; 

< 

struct NewScreen NewScreen; 

NewScreen. Lef tEdge=0; 
NewScreen. TopEdge=y; 
NewScreen. Width=w; 
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Figure 3-4. Drawing in interlace mode 



Cycle 1 J 
200 lines \ 



o 
o 
o 



> 



Cycle 2 
200 lines 
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Listing 3-9. Creation of a high-resolution interlaced screen and 

window. 



Sinclude <exec/types.h> 

#i nc lude <i ntui t i on/ i ntui t i on . h> 

#incLude <graphics/display.h> 



struct IntuitionBase *IntuitionBase; 
struct Window *wind; 
struct Screen *Scrn; 

•define INTUITION_REV 33 



mainO 



{ 

ULONS flags; 
SHORr x,y,w,h,d; 
USHORT mode; 
UBYTE *name,c0,d; 
VOID delay funcO; 



/* ======Open Intuition======= */ 



IntuitionBase=(struct IntuitionBase *) 

OpenLibraryO'intuition. library", INTUITI0N_REV) ; 

if (IrttuitionBase==NULL) 
eti t (FALSE) ; 
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Listing 3-9. (cont.) 



/* ======0pen a hi-res custom screen==== */ 

name="High Resolution Screen"; 

y=0; 

w=640; 
h=400; 
d=3; 

c0=0x00; 
c1=0x01; 

mode=HIRES| INTERLACE; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1, mode, name); /* error check */ 

/* =======And a window==============*/ 

name="Window"; 

x=20; 

y=20; 

w=300; 

h=100; 

f lags=ACTIVATE; 
c0=-0x01 ; 
c1=-0x01; 

wind=(struct Window *) 

make_window(x, y,w,h, name, f lags, c0,c1 ,Scrn) ; /* error check */ 

/* ======Delay for a bit to show off the window====== */ 

delay_func(100); 

/* s========ciose down the window then the sq 

CloseWindow(wind) ; 

CloseScreen(Scrn) ; Z B B O 

> zaragoza 



Oil MAT 



make_wi ndow(x,y,w,h, name, flags, co lorO, co lor1 .screen) 

SHORT x,y,w,h; 

UBYTE *name,color0,color1 ; 

ULONG flags; 

struct Screen *screen; 

/* This function will initialize the NewWindow structure 
and open the window */ 

{ 

struct NewWindow NewWindow; 
NewWi ndow . Lef t Edge=x ; 
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odular Programming 

You may have noticed that our example programs are becoming unwieldy 
because of the complexity of Intuition. While we have made some small steps 
towards the management of this complexity— separate functions for opening 
windows and screens, for example— the C programming language allows us 
to go much further. 

An executable C program is created in two stages: compilation and 
linking. Each step is independent of the other. It is possible to put individual 
functions into separate files, and then compile each file independently of the 
others. This separate compilation produces a file that is midway between the 
source code on the one hand and an executable program on the other. These 
files are incomplete and contain a mixture of executable code and references 
to routines outside of the current file. In addition, their addresses have to be 
reconciled. These object files can be combined by the linker to produce a 
program file. Figure 3-5 illustrates this process. 

One important advantage of separate compilation is that we can sepa- 
rate functions that are common to many programs and place them into one or 
more files, compile these files, and just link the resulting object code with any 
program that might need those functions. For example, in every program 
that we have created so far, a call to OpenLibrary( ) is necessary to set up the 
Intuition environment. This operation along with its supporting declarations 
can be exported to a file. Listing 3-10 shows the contents of a file that will set 
up this environment. 

Listing 3-10. A file to open Intuition. 



/(include <exec/types.h> 
/(include <intui Eion/intuition.h> 

struct IntuitionBase *IntuitionBase; 

(/define INTUITION_REV 33 /* set the revision number of Intuition */ 

/* Open ALIO sets up the intuition environment for the user. Error 
checking should be added*/ 

Open UK) 
{ 

IntuitionBase=(struct IntuitionBase *) 

OpenLi brary ("intuit ion. library", INTUITION_REV> ; 

i f ( Intui t i onBase==NULL) 
exit (FALSE); 

> 
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This file is a semiautonomous unit containing declarations, references to 
standard include files, as well as a function that does the actual work. In this 
way, a collection of useful functions can be assembled which will serve many 
applications without the necessity of making them part of the application 
code itself. The code is, therefore, cleaner and easier to read. 



Listing 3-1L The screen support function — S_sup.C. 

/(include <exec/types.h> 
(((include <i ntui t i on/intuit ion. h> 
/(include <graphics/display.h> 

/*make_screen() will open a screen with the suppLied characteristics. 
Add error checking*/ 

make_screen(y,w,h,d,color0,color1 .mode, name) 

SHORT y.w.h.d; 

UBYTE colorO.colorl ,*name; 

USHORT node; 

< 

struct NewScreen NewScreen; 



NewScreen. LeftEdge=0; 
NewSc reen . TopEdge=y ; 
NewScreen. Width=w; 
NewScreen.Height=h; 
NewSc reen . Dept h=d ; 
NewScreen. Detai lPen=colorO; 
NewSc reen .Bloc kPen=co lorl ; 
NewSc reen . Vi ewModes=mode; 
NewScreen. Type=CUSTOMSCREEN ; 
NewScreen. Font=NULL; 
NewScreen. DefaultTitle=name; 
NewScreen. Gadgets=NULL; 
NewScreen. CustonBitMap=NULL; 



/* initialize a NewScreen object */ 



FORMAT 

R O 

G O Z A 



2 

2 A R 



return(OpenScreenCSNewScreen)); /* return the address of the screen */ 



We can create similar files to handle window and screen creation— two 
operations that are shared by nearly all Intuition programs. Listing 3-11 
shows s_sup.c, a screen support function and Listing 3-12, w_sup.c, a func- 
tion for windows. In both cases, the file may be independently compiled and 
linked into a program as needed, providing a necessary resource that can be 
called upon whenever these functions are needed in a program. In the exam- 
ples which follow, we assume that the functions defined in these three files 
are available to the program being discussed, and we do not explicitly men- 
tion them. 
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^include <exec/types.h> 
^include <intuiti'on/intuition.h> 

/* make_window<) will open a window in the specified screen and with the 

indicated characteristics. More error checking is needed*/ 

make y i ndow (x, y, w, h, name, f lags, i flags, colorO, coloM .screen) 

SHORT x,y,w,h; 

UBYTE *name,color0,color1 ; 

ULONG flags; 

USHORT if lags; 

struct Screen *screen; 

{ 

struct NewUindow xNewWindow; 

NewWindow. LeftEdge=x; /* initialize a NewWindow object */ 

NewWi ndow . TopEdge=y ; 
NewWindow. Width=w; 
NewWindow. Height=h; 
NewWindow. Detai lPen=colorO; 
NewWindow.BlockPen=color1 ; 

NewWindow. Title=name; . 
NewWindow. Flags=f lags; IkJf ** 

NewWi ndow . I DCMPF lags=i f lags ; 



if (screen == NULL) 

NewWi ndow. Type=WBENCHSCREEN; 



I 



NewWi ndow. Type=CUSTOMSCREEN; *^ » Q U*" 

NewUindow. Screen=screen; «■* fV. K 

> 

NewUindow. FirstGadget=NULL; 
NewUindow. CheckMark=NULL; 
NewWindow. Screen=screen; 
NewWi ndow. BitMap=NULL; 
NewWi ndow. MinWidth=0; 
NewUindow. Mi nHeight=0; 
NewWi ndow. MaxUidthO; 
NewWi ndow.MaxHeight=0; 

return(OpenWindowCSNewWindow)); /* return the address of the window */ 

> 



The exact format for compiling and linking these files varies according 
to the particular compiler/linker being used and may even vary from one 
version to the next. It's always wise to check the current manual. With the 
Lattice compiler and the alink linker the format is 

— compi ling 

Ic -i INCLUDE: prog.c 

Ic -i INCLUDE: i_sup.c 

Ic -i INCLUDE: s sup.c 

Ic -i INCLUDE: w sup.c 
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where 

lc is the driver program supplied with the compiler 

prog.c is an application program 

i_ sup.c etc. are the various support files 

INCLUDE: is the directory that contains the system header files 
— linking. . . 

alink LIB: Lstartup.obj+prog.o+1_sup.o+s_sup.o+w_sup.o 
to prog LIB LIB: lc. lib+LIB:amiga. lib 

where 

alink is the linker 

Lstartup.obj is the standard startup routine 

lc.lib and amiga.lib are library files 

prog.o, i_sup.o, etc. are object files 

LIB: is the directory containing the standard libraries. 

It must be noted that there are important variations and shortcuts for these 
command lines. 



ets 

One of the most difficult tasks when using a window system such as Intuition 
is to set up channels of input and output. Each window and screen available 
to the user is a complex object with many changeable characteristics. It is 
not enough to send a few characters or a picture to a specific window. Things 
like its current position, size, and mode of activity must be known, as well as 
parameters such as font type and color. Getting values back from a window 
involves these problems as well as user interaction and movement around the 
display area. Intuition contains several subsystems that help to reduce the 
complexity of this problem. One of the most interesting of these is the gadget 
subsystem. 

A gadget is a kind of "software machine." It is an input procedure set up 
to mimic some kind of physical control device. Frequently gadgets are dis- 
played graphically to dramatically indicate their function. Other times they 
are rendered with text, but always with an eye to attracting the user's atten- 
tion. The use of gadgets is linked to the mouse; even gadgets whose main 
function is to gather text frequently use the mouse to initiate a gadget 
session. 

The "real world" orientation of these devices is underscored by the four 
types of gadgets that can be defined: 

• Boolean gadgets ask a yes or no question; they return true or false. 

• String gadgets look for a character string. 



65 



Using Intuition 



• Integer gadgets accept only a signed or unsigned string of digits. 

• Proportional gadgets allow the user to specify a fraction or portion of 
a value. 

The proportional type is the most flexible of all the gadget types. It 
offers a kind of input conversion that is difficult to accomplish: the transla- 
tion of analog values into a form with which the computer can deal. 

Gadgets are usually associated with windows, but they can also be 
attached to screens, outside of any particular window. This is another factor 
adding to their flexibility. When defined inside a window, they can be set up 
to share in any changes to that window. A difference in size or position will all 
be reflected in a proportionate change to the gadgets. 



System Gadgets 

Intuition offers four built-in gadgets that can be easily added to any window: 

L The Sizing Gadget allows the user to alter the size of a window 
dynamically. 

2. The Depth Gadget adjusts the relative position of windows that 
overlay one another. 

3. The Drag Gadget allows a window to be moved around the screen and 
then deposited at a new location. 

4. The Close Gadget signals the owner of a window that the user wants 
to shut it down. 

The Sizing and Depth Gadgets can be used for screens as well as win- 
dow;!. In fact, when a screen is opened, these two gadgets are automatically 
attached. System gadgets must be specifically assigned to a window, how- 
ever, either at the time of window creation or through the AddGadgetf ') 
function. Figure 3-6 illustrates these gadgets. 

System gadgets always appear in the same place in the borders of a 
window or screen. Because of this, they represent a consistent interface to the 
user. No matter what application is being run: 

• The Sizing Gadget is always in the lower right-hand corner of the 
display. 

• The Depth Gadget is in the upper right-hand corner. 

• The Drag Gadget is found in the title bar. 

• The Close Gadget resides in the upper left-hand corner of the window 
or screen. 

These locations are within the borders of the window or screens. These 
borders are adjusted to a greater width necessary for displaying them. 
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Figure 3-6. Illustrating the system gadgets 
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It is easy to add the system gadgets to a window at the time of its 
creation. This is done through the Flags field of the NewWindow structure. 
Each gadget has its own flag: 

• WINDOWSIZING indicates a gadget that will allow the user to 
change the size of an open window. 

• WINDOWDEPTH installs a gadget that will allow the user to move 
one window in front of another. 

• WINDOWDRAG creates a gadget that will allow the window to be 
moved by the mouse. 

• WINDOWCLOSE indicates that the user wishes to shut down a 
window. 

By specifying one or more of these flags, the corresponding gadget will 
be automatically placed in the window when it is displayed. 

Listing 3-13 illustrates a program that creates a window containing 
these system gadgets. In fact, the program opens two windows in a high- 
resolution custom screen; each has the full range of system gadgets. To 
specify these gadgets, add their appropriate flags to the Flags member of the 
NewWindow structure. 
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Listing 3-13. Endowment of two windows with the 
standard gadgets. 



"include <exec/types.h> 
"include <i ntui t i on/ intuit ion. h> 

struct Screen *Scrn; 

struct Window *wind0,*wind1 ; 

main() 
< 

ULONG flags; 



"«*n. Tiags; n Q 1. 

SHORT x.y.w.h.d; _ 
USHORT mode; A 
UBYTE •name.cO.d; 
VOID delay.funcO; 

ODtnAUO; 

/* ■■K===o p en a hi-res custom screen==== */ 

n«B*«"The Gadget Screen"; 

VO; 

w«6*0; 

h«200; 

d«S; 

cCOxOO; 
c1«Ox01; 
■«I«*HIRES; 

S«rn«(struct Screen *) „u„,.i,;„n */ 

/ k ^ »i »nri» name): /* Add error checking */ 
make screen<y,w,n,d,cO,c1 ,"Ooe,nainB^ , 



/* »««====open a window=========-=* / 

"♦••■••window 1"; 

w*JOQ; 

^»SS=*CTIVATE|WINDOWSIZING|WIND0WDEPTH|WIN0OWORAG| 

WINOOWCLOSE | SHARTJJEFRESH ; 

fO*-Ox01 ; 
•:I*-Ox01 ; 

w"NdO=(struct Window *) . „„„_ 

make_window(x,y.w,h, name. flags. cO.cl.Scrn); /• Add error 

checking */ 

V* «=====open another window== 
''••♦■•■Window 2"; 

««$Xl; 
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Listing 3-13. (cont.) 



f lags=ACTIVATE|WINDOWSIZING|WIND0WDEPTH|WINDOWDRAG| 

WINDOWCLOSE | SMART_REFRESH ; 

c0=-0x01 ; 
d=-0x01; 

wind1=(struct Window *) 

make_wi ndow (x , y , w , h , name , f lags , cO , d , Sc rn) ; 

/* ======0elay for a bit to show off the window====== */ 

delay_func(100); 

/* =========ciose down the window then the screen========*/ 

CloseWindow(windO); 
CloseWindow(wind1 ) ; 
CloseScreen(Scrn) ; 

> 



Once you create a window and specify which of the system gadgets you 
desire, they are— with the exception of the Close Gadget— immediately availa- 
ble. If you position the mouse cursor at the Sizing Gadget, select it, and move 
the cursor inward, the window gets smaller. An outward movement reverses 
the process; it gets larger. By using the Drag Gadget, you can move the 
window vertically and horizontally around the screen. The Depth Gadget 
allows you to rearrange overlapping windows. All of these functions are 
performed by Intuition. The commands represented by these gadgets are, in 
fact, trapped and never even reach the application controlling the window. 
There are two exceptions: the Close Gadget and the size verify function. Both 
of these must be handled explicitly by the program that controls the window. 
They are not handled automatically. 

The Close Gadget does not affect the display of its window. If you 
indicate through it that the window is to be shut down. Intuition sends a 
message to the controlling application that this particular gadget was se- 
lected. It never takes it upon itself to close down a window. It is always 
necessary— except perhaps in the case of small demonstration programs— to 
perform clean-up and bookkeeping operations on an application, before it can 
leave the screen. In any case. Intuition leaves it up to the application whether 
or not to actually close the window. Similarly, you can set a flag in the 
NewWindow structure that will perform the same kind of hold on the Sizing 
Gadget. This is the SIZEVERIFY flag; it goes in the IDCMPFlags field of 
the NewWindow structure. We will return to this later when we discuss the 
IDCMP input/output system. 

Our example also shows a new parameter, which must be set to support 
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the Sizing Gadget. You must specify both the minimum and the maximum 
size that a window can change. This is accomplished by setting MinWidth, 
MinHeight, MaxWidth, and MaxHeight in the NewWindow structure. Note 
that a window does not have to initially appear at its minimum size, but if you 
initialize the MinWidth or MinHeight fields to 0, these will be automatically 
set to these initial values. In the example, we have set the minimum values to 
1. This will not allow the window to disappear from the screen, but it does 
allow the user to shrink it so that it nearly disappears. 



Application-Specific Gadgets 

Intuition also gives you the option of creating a customized gadget to meet a 
special-purpose input situation. These special-purpose gadgets can take on 
many shapes and formats, and are frequently displayed as striking graphic 
images. Their form is limited only by the imagination of the programmer. In 
this chapter we can only scratch the surface and talk about the technical 
requirements. 

Custom gadgets are defined through a structure data type. This one 
takes the form: 

struct Gadget { 

struct Gadget *NextGadget ; 
SHORT LeftEdge, TopEdge, 

Width, Height; 
USHORT Flags, 

Activation, 

GadgetType; 
APTR GadgetRender, 

SelectRender, 
struct IntuiText *GadgetText; 
LONG Mutua [Exclude; 
APTR Speciallnfo; 
USHORT GadgetID; 
APTR UserData; 

> 

Only a few of these fields concern you now. More will be of interest to 
you later, when we turn our attention to drawing gadgets instead of merely 
writing out text. 

LeftEdge and TopEdge are concerned with positioning the gadget in the 
window. System gadgets are always found in the borders of windows or 
screens, but customized gadgets can appear anywhere. This is a manifesta- 
tion of their flexibility. Width and Height must be set in concert with the two 
coordinate fields to get a reasonable display. 

The Flags member controls several display characteristics of the gadget, 
most importantly, how it is to be highlighted when it is chosen. There are 
several possibilities: 

. GADGHCOMP produces highlighting by turning the color of a 
chosen gadget to a complementary value. 
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• GADGHBOX draws a box around the selected item. 

• GADGHIMAGE displays an alternate picture, supplied by the 
application, to indicate selection. 

• GADGHNONE is set when no highlighting is desired. 

This field controls several other characteristics. Following is a complete 
description of all values for the gadget flags field. 

GADGHCOMP. 



Highlighting is indicated by setting the select 
box to complement. 

Highlighting is indicated by a box around the 
select box. 

Highlighting is indicated by an alternate image 
or border. 

This specifies no highlighting. 
This flag indicates that an image has been 
supplied for the gadget. 

This indicates that TopEdge is an offset from 
the bottom of the containing element. 
This indicates that LeftEdge is be calculated 
from the right edge of the containing element. 
This is set to interpret Width as an increment 
to the width of the containing element. 
This causes Height to be interpreted as an 
increment to the containing element's height. 

This indicates that the initial state of the 
gadget is "selected". 
This disables the gadget. 

The Activation field sets a similar set of characteristics for the gadget 
itself. TOGGLESELECT, for example, produces a gadget whose state is 
changed back and forth by the same select field. Each time it is selected by 
the user, it changes from its current state to its other state. This works much 
like a pushbutton switch on a lamp. 

The Gadget Type member indicates one of three possible types: 

• BOOLGADGET indicates a boolean or yes-no gadget. 

• STRGADGET specifies one looking for character string input. 

• PROPGADGET specifies a gadget that will accept and specify a 
proportional numeric value. 

There is one additional type, the integer, which is a variant form of the 
string type. 

The MutualExclude member allows you to control the interaction of 
individual gadgets. Specifically, this field indicates which of the other gad- 
gets defined for the window must be de-selected when the gadget in question 



GADGHBOX. 

GADGHIMAGE. 

GADGHNONE. 
GADGIMAGE. 

GRELBOTTOM. 

GRELRIGHT. 

GRELWIDTH. 

GRELHEIGHT. 

SELECTED. 

GADGDISABLED. 



71 



Jsing Intuition 



becomes the current one. Any gadgets that appear on this list will immedi- 
ately be de-selected, when this gadget is selected. 

Listing 3-14 shows the definition of a string gadget in a window. One 
additional step was necessary to bring this object to the display: the initial- 
ization of a Stringlnfo structure. This is one of two special purpose data 
types used to initialize the Speciallnfo field of the gadget structure. It has 
the general form: 

struct Stringlnfo I 
UBYTE *Buffer, 

♦UndoBuf f er; 
SHORT BufferPos, 

MaxChars, 

Di spPos, 

UndoPos, 

NumChars, 

DispCount, 

CLeft.CTop; 
struct Layer *LayerPtr; 
LONG Longlnt; 
struct KeyMap *AltKeyMap; 

>; 

where 

Buffer points to a buffer. 
UndoBuffer points to a backup buffer. 

MaxChars contains the number of characters in the buffer. This 
includes the '\0' character. 

BufferPos indicates the initial position of the cursor. 
DispPos is the position of the first displayed character. 
UndoPos indicates the cursor position in the undo buffer. 
NumChars is the current number of characters in the buffer. 
DispCount indicates the number of characters visible. 
CLeft, CTop is the offset of the containing box. 
LayerPtr points to the Layers structure. 
Longlnt contains the value if this is an integer gadget. 
AltKeyMap points to an alternate key map. 

Only a few fields need to be set to implement this object. 

Buffer points to an area in the memory that is set to receive the charac- 
ters that will come in from the gadget. It may be preset with a value; this 
preset value can be replaced by the user. If no value is entered, the preset 
value becomes default value. The DispPos field indicates which characters in 
this default string will be displayed. In our example, we show the entire 
string, so this value is 0. It is also necessary to indicate to Intuition the size 
of the string expected; this is done through the MaxChar field. BufferPos 
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indicates the initial position of the cursor in this buffer. Our example puts 
this, too, at the beginning. 

Listing 3-14. Endowment of a window with a string gadget. 



^include <exec/types.h> 
#i nc Lude <i ntui t i on/ i ntui t i on . h> 

struct Screen *Scrn; 
struct Window *wind0,*wind1 ; 
struct Gadget gadget; 
struct Stringlnfo info; 

mainO 
{ 

ULONG flags; 
SHORT x,y,w,h,d; 
USHORT mode; 
UBYTE *name,c0,c1; 
VOID delay_func(),0penALLO; 
char dobuffertoO] .undobuf f erC80] ; 

OpenALLO; /* Add error checking */ 

/* ======First create a gadget ======== */ 

strcpy(dobuf fer, "Enter New Text Here"); 

info.Buf fer=dobuf fer; 
info.UndoBuf fer=undobuf fer; 
info.MaxChars=80; 
info.Buf ferPos=0; 
info.DispPos=0; 

gadget .NextGadget=NULL; 
gadget . Lef tEdge=40; 
gadget .TopEdge=40; 
gadget. Width=200; 
gadget. Height=75; 
gadget . F lags=GADGHCOMP; 
gadget.Activation=TOGGLESELECT; 
gadget .GadgetType=STRGADGET; 
gadget . GadgetRender=NULL; 
gadget .SelectRender=NULL; 
gadget. Gadget Text=NULL; 
gadget .MutualExc tude=NULL; 
gadget .Special Info=(APTR) Si nfo; 
gadget . Gadget I D=NULL; 
gadget. UserOata=NULL; 

/* ======0pen a hi -res custom screen==== */ 

name="The Gadget Screen"; 

y=0; 

w=640; 



FORMAT 

Z E R O 

ZARAGOZ A 
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Listing 3-14. (cont.) 



h=200; 
d=3; 

c0=0x00; 
c1=0x01 ; 
mode=HIRES; 

SC " n=(St :aKljc:ren(;Iw,h.d,c0.c 1 . m o d e.na m e); /* Add error checking ./ 
/* =======Open a window==============*/ 

nane="Window 1"; 

x=>0; 

y=20; 

w=;00; 

f Ugs=ACTIVATE | WINOOWSIZING | WINDOWDEPTH | wINOOUDRAG | 

WINDOWCLOSE | SMART_RE FRESH ; 

c0=-0x01 ; 
c1=-0x01 ; 

windO=Cstruct Window *) . 

make_window(x,y,w,h, name. f lags, cO.cl.Scrn.&gadget), 

/. ======oeLay for a bit to show off the window====== */ 

d«Lay_func(100); 

/* =======«<: lose down the window then the screen===.=====*/ 

CloseWindow(windO); 
C.oseScreen(Scrn) ; 



The UndoBuffer is an optional field. If specified with something other 
than NULL, it is used to save the initial string value. This imtiates the built- 
in undo editing function: the sequence "Right Amiga Key-Q will clear the 
current buffer value and return the original string of characters The . Un- 
doBuffer may be shared among all the gadgets in a window but it must be 
large enough to hold the largest string. We have implemented the UndoBuffer 

in our example. . . . . . . 

Once a gadget has been defined, it is implemented by assigning it to the 
FirstGadget field in the NewWindow structure. It is then added to the win- 
dow when the window is opened. The AddGodgetf) function ahows us to put 
new gadgets onto the list of an open window. RemoveGadgetf ) performs the 
complementary task. The RefreshGadgetf ) function will cause it to appear. 

Listing 3-15 shows an example of an integer gadget. This is a string 
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gadget whose values are restricted to strings of digits. It is set up in just the 
same way as our earlier example. It, too, uses a Stringlnfo structure. The 
difference is the setting of the LONGINT flag in the Activation field of the 
gadget structure. 

Listing 3-15. Endowment of a window with an integer gadget. 



#include <exec/types.h> 
^include <intuition/intuition.h> 

Format 

2 E h O 

2 ARAGOZ A 



OpenALLO ; 

/* ======First create a gadget========= */ 

strcpy (dobuf f er,"0") ; 

info.Buf f er=dobuf f er; 
info.UndoBuf f er=undobuf fer; 
info.MaxChars=80; 
info.BufferPos=0; 
info.DispPos=0; 

gadget. Next Gadget =NULL; 
gadget. LeftEdge=40; 
gadget .TopEdge=40; 
gadget. Width=200; 
gadget. Height=75; 
gadget . F Lags=GAOGHCOMP; 
gadget . Act i vat i on=TOGGLESELECT | LONG INT; 
gadget . Gadget Type=STRGADGET; 
gadget .Gadget Render=NULL; 
gadget . Select Render=NULL; 
gadget .Gadget Text=NULL; 
gadget .Mutua LExc lude=NULL; 
gadget . Speci a I Inf o=(APTR) Si nf o.- 
gadget .Gadget ID=NULL; 
gadget .UserData=NULL; 

/* ======Open a hi-res custom screen==== */ 

name="The Gadget Screen"; 



struct Screen *Scrn; 
struct Window *wind0,*wind1 ; 
struct Gadget gadget; 
struct Stringlnfo info; 

mainO 
{ 

ULONG flags; 
SHORT x,y,w,h,d; 
USHORT mode; 
UBYTE *name,cO,d ; 
VOID de lay_f unc () , OpenALLO ; 
char dobuf ferC80] ,undobufferC80] ; 
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Listing 3-15. (cont.) 



FORMAT 



y=0; 
w=640; 

cC=6x00; 7AGA60Z A 

d=0x01; i A K M W ^ *- 

mcde=HIRES; 

Scrn=(struct Screen *) 

raake_screen(y,w,h,d,c0,c1 .mode, name) ; 

/* =======Open a wi ndow==============*/ 

name="Window 1"; 

x=20; 

y=20; 

w=400; 

h=150; 

f lags=ACTIVATE|UIN0OWSIZING|UINDOW0EPTH|WINDOWDRAG| 

WINDOWCLOSE | SMART_REFRESH ; 

c0=-OxO1 ; 
d=-0x01; 

windO=(struct Window *) 

make_w indow(x,y,w,h, name, flags, cO.d ,Scrn,8gadget) ; 

/* ======Delay for a bit to show off the window====== */ 

delay_funcC100); 

/* =========ciose down the window then the screen========*/ 

CloseWindow(windO) ; 
C loseScreen(Scrn) ; 

> 



Menus 

Everyone who programs is familiar with the notion of a menu: a list of choices 
that affect the flow of a program by offering the user a selection of options for 
program control. 

The menu is one of Intuition's most basic data objects. As such it is easy 
to define and easy to set up for dramatic display. Unlike gadgets, which can 
be in a window or in a screen, the menu is solely a creature of windows. Each 
window may contain a linked list of such menus— the menu strip. The menu 
always appears in the title bar of the enclosing screen. When chosen by the 
right mouse button, the menu rolls down from the top. 
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Each menu consists of a table of choices. The user must indicate which 
item or items listed in this table are desired. There are several methods of 
choice, dependent both upon the design and the nature of the items in ques- 
tion. The primary methods are: 

1. Toggles that stay on until explicitly turned off 

2. Choices that remain as long as the mouse button is depressed 

It is also possible to set up a menu so that several items can be selected 
by touching each in turn with the mouse cursor. 

Toggled items share an important characteristic: they can be set to be 
mutually exclusive. Choosing one item precludes the choice of others in the 
prescribed list. Moreover, the choice of a mutually exclusive alternative to an 
item that is presently toggled on causes that item to be de-selected. 

Although menus depend heavily on the Intuition interface of windows and 
screens and the convenience of pointing with the mouse, it is possible to set up a 
keyboard alternative for all or a selected set of menu items. These alternatives 
use the special Amiga keys on the keyboard to define an escape sequence of 
characters, which will automatically choose the menu item in question without 
resort to the menu. When a keyboard alternative is set up, a special mark is 
displayed in the visual menu to indicate that this is a possibility. 

Defining Menus and Menu Items 

A menu is defined by a properly initialized menu structure. Unlike the win- 
dow, screen, or even the gadget structure, this is a relatively simple data 
object. 

struct Menu { 

struct Menu *NextMenu; 
SHORT LeftEdge.TopEdge, 

Width, Height; 
USHORT Flags; 
BYTE *MenuName; 
struct Menultem *Fi rstltem; 

>; 

The first field, NextMenu, is the link to the next menu in the chain for 
this window. There is only a single string of menus in each window. Remem- 
ber to set this field either to the address of the next menu or to NULL, if this 
is the last one. 

LeftEdge sets the position of the menu header in the screen title bar; it 
indicates how far from the left-hand side of the display the header will appear. 
The Width field indicates the horizontal size of the menu header and its 
corresponding select box. In the current implementation of Intuition, both 
TopEdge and Height are not used. All menu headers appear at the top of the 
screen title bar. 

The Flags field allows the application to communicate with Intuition. 
Currently two flag values are defined and set by Intuition: 
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. MIDRAWN indicates the current display state of the Menu- whether 

or not the menu is being shown to the user. 
. MENUENABLED indicates whether or not a particular menu will be 

available to the user. 

If the MENUENABLED flag is not set, then the menu is disabled. If 
the flag is set, however, the menu can be controlled by the functions 
OnMenuf) and OffMenu. The former enables, the latter disables the menu. 
The format for these functions is as follows: 

OnMenu(w_ptr,m_num) 
where 

w_ptr points to a window. 
m_num is a menu number. 

This function activates menu, menu item, or sub-item according to the 
m_num identifier. 

OffMenu (w_pt r , ra_num) 
where 

w_ptr is a pointer to a window. 
m_num is a menu number. 

This function de-activates the corresponding object. 

It is important to note that even if the menu is to be initially disabled, 
this flag must be set and the menu disabled through the function. Failure to 
do this will result in a permanently disabled function.' 

MenuName is a pointer to a character string that contains the text that 
is to appear in the menu header. It is the title of the menu. As a matter of 
style, it is important that this string fit nicely into the specified width of this 
header The menu structure serves to set out the header and the title, and 
specifies the position and width of the object. In order to create a complete 
menu, we must also have some choices for the user to make. These choices are 
added through the initialization of a Menultem structure. Each item in the 
menu is represented by one of these structures, connected together m a linked 
list. The Firstltem field in the menu structure points to the head of this list. 

The Menultem structure consists of eleven fields: 

struct Menultem { 

struct Menultem *NextItem; 

SHORT LeftEdge,TopEdge, Width, Height ; 

USHORT Flags; 

LONG MutualExclude; 

APTR ItemFUl; 

BYTE Command; 

struct Menultem *SubItem; 

USHORT NextSelect; 

>; 
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This structure is the real workhorse of the menu subsystem. It is more 
complex than the menu structure itself, although many of its fields are op- 
tional. There are two pointer members in this structure. 

• Nextltem points to the next structure in the chain of items that define 
the menu. The last structure in this chain must set this field to NULL. 

• Subltem defines another linked list attached to the item; these are 
also defined using the Item structure. The Subltem field can support 
its own dependent linked list. 

Figure 3-7 details the relationship of items and sub-items. 
Figure 3-7. The relationship of item and sub-item 
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Each item in the menu is displayed in its own select box. This is the area 
that the mouse cursor must access in order to choose the item. LeftEdge and 
TopEdge position the select box. As with all Intuition structures, the point 
whose coordinate is represented by these two fields is relative to the left-hand 
corner of the enclosing structure, the menu box. The Width and Height fields 
round out the item select box definition. It should be noted that the select 
box need not have the same dimensions as the menu header. 

The MutualExclude flag is used to specify which items in this menu are 
incompatible with the item being defined. Any items indicated here will be 
automatically de-selected whenever the user chooses this item. The field itself is 
a bit map defined on a long word. This puts a limit of thirty-two on the number 
of items that can be mutually excluded. Each bit position is assigned to a 
particular item number. A 1 bit in the position indicates a chosen item. Figure 3- 
8 illustrates this member of the structure; it is only valid for toggled items. 
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Figure 3-8. Setting the MutualExclude flag for a menu 
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Itemfill contains a pointer to one of two structures: 

1 If the item is to be rendered by text, it points to an IntuiText structure. 

2 If the item is to be a graphic one, then the field must contain the 

' address of a user-defined BitMap. This latter is an area of memory 
formatted and managed to store an image of the display. 
The SelectFM field also points to one orthe other of these ■Structures to 
snecifv the highlighting of a chosen item. The Command field allows us to 
sSSfy an alSS keyboard sequence to choose the item. This is an escape 
SauSrdefced. first of all, by one of the special Amiga keys on either side of 
S space b? This escape sequence allows the user to directly choose a menu 
atd itom ^hout recoup to the screen £ ™<J™ f^<*^ ^TSS 
sequence is trapped, it is treated no differently than if the menu had been 

"""E S STSSZ the ^ S field is used to communicate with 
Intuition on behalf of the particular item being defined. For menu ^ems tins 
set of flags is correspondingly complex, since they control so many of the 

^ SPl The CHECKIT flag is used to specify the kind of item being defined. If 
this flag is set, you are specifying a toggle item-one that is turned on and off 
by subfequen selections. If the flag is unset, the item is only selected mo- 
menSy while the mouse cursor is positioned over it and the button pressed 
H CHECKED is also set, a check mark is displayed by the item when it is 
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shown. It should be noted here that extra space must be left for this check- 
mark when declaring the dimensions of the select box for this item. 

The ITEMTEXT flag is set if the item is a text-only one. This is comple- 
mentary to the ItemFill field and indicates which structure this pointer indi- 
cates. COMMSEQ indicates that an alternative command sequence has been 
defined. 

ITEMENABLED functions in the same way as the MENUENABLE 
flag. If this is not set, the item is not enabled and its status cannot be 
changed. The display is "ghosted" to indicate this to the user. If this flag is 
set, then the status of the item can be manipulated by OnMenuf) or 
OffMenuf). These perform the same function on individual items as they do 
on whole menus. 

When a menu item is selected, its display is highlighted. The Flags field 
contains a specification which sets the form of this highlighting. 

• HIGHCOMP changes the entire select box to its binary complement. 

• HIGHBOX encloses the select box with an outer rectangle. 

• HIGHIMAGE replaces the original display with the alternative 
specified in the SelectFill field. 

• HIGHNONE turns off any highlighting of the display. 

There is no default. One of these alternatives must be explicitly speci- 
fied. 

Intuition sets the ISDRAWN and HIGHTEM flags. The former indi- 
cates that an item's sub-items are being displayed. It is cleared when this is 
no longer the case. The latter flag is set to show highlighting of an item. 



Creating a Menu 

Once you have defined each item in the menu, combined these items into a 
list, and attached it to a menu definition, you still have to associate it with a 
particular window. This association is controlled by SetMenuStripl) and 
ClearMenuStripO. These two functions allow you to dynamically create and 
change the menus within your applications. Two additional functions 
OnMenuf ) and OffMenuf) afford even greater control by allowing you to turn 
specific menus or menu items on and off, without removing them from their 
respective lists. Finally, Intuition offers a function, ItemAddressI ), to capture 
the address of a particular Menultem structure. 

SetMenuStripl ) takes a pointer to a window and a pointer to a menu 
structure as arguments. Intuition automatically attaches the menu strip 
defined by this pointer to the window in question. 

There may be many menus in a window— even unrelated ones— but they 
must all be connected together in this menu strip. Each window has only one 
such strip. In recognition of this fact, the ClearMenuStripO function requires 
only a window pointer, to remove all menus. Any application that is to change 
a menu or item must first clear the menu strip and then make another call to 
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SetMenuStripf). This process can occur any number of times. The format of 
these two functions is as follows: ■ 
SetMenuSt ri p(w_pt r , m_pt r) 

i where 

w_ptr points to a window. 

m_ptr points to the first menu in the menu strip. 
This function will install the menu strip in the window. 
ClearMenuStrip(w_ptr) 
where 

w_ptr points to a window. 

This function will remove the current menu strip from the window. 

The complementary functions OnMenuO and OffMenuO control the 
menu and items once they are established in the window. Each function takes 
a window pointer and a MenuNumber as an argument and performs its task 
on the object so identified. The MenuNumber is an Intuition variable that 
identifies the menu-related object currently picked; this quantity allows you 
to specify either an entire menu, an item, or a sub-item An object that s 
disabled appears to the user with a light pattern of white dots across it 
(ghosting) to indicate its status. The format for these functions is: 

OnMenu(w_ptr,m_number) 
when; 

w_ptr points to a window. 
m_number is a menu item number. 
This function enables the specified menu or menu item. 
Of f Menu (w_pt r ,m_number) 
where 

w_ptr points to a window. 
m_ number is a menu item number. 
This function disables the specified menu or menu item. 
The menu number is an important parameter for all menu-rela ed func- 
tions. You can use it to do selective enabling or disabling o ^ ticula f 
objects- but it is also important for communicating choices to the controlling 
apphca ion. This number is sent through Intuition's IDCMP acuity, a spe- 
dahzed communication method peculiar to Intuition. We wffl discuss the 
medium and technique for this facility in a later section. Once you have this 
value, it is still necessary to decode it into its exact reference. 

The menu number is a composite value, giving the users choice as. 
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• A particular menu ■» . * 

• A particular item in that menu & O Z j\ 

• A sub-item attached to the item 

These values are combined into a single LONG word value. Each menu 
is assigned an ordinal value in the menu strip, which is the menu number. 
Each item is similarly numbered within its menu, and the same is true of each 
sub-item. Intuition supplies several macros to perform the necessary decod- 
ing. 

MENUNUM( ) returns the menu number. 
ITEMNUM( ) finds the item number. 
SUBNUM( ) gives us the sub-item number. 

You need all three of these numbers to define a reference since a sub-item 
is relative to an item, which in turn is relative to a menu. 

The absence of a menu selection is signaled by the value MENUNULL. In 
addition, there are three flags which you can use to indicate a null condition to 
Intuition: NOMENU, NOITEM, and NOSUB. Although the reference objects 
of these latter flags are obvious, how they are used may not be. One important 
use for these constant values is in the OnMenul )/OffMenu< ) functions: 

• Setting the item field to NOITEM causes the function to operate on the 
entire menu. 

• Setting the sub-item field to NOSUB affects only the item. 

• Setting none of the fields in a menu number causes the function to work 
only on the indicated sub-item. 

Finally, the function ItemAddre.ts( ) takes a pointer to a MenuStrip and a 
MenuNumber and returns a pointer to the object thus specified. These menu- 
related functions are summarized as follows: 

address=ItemAddress(m_strip,m_number) 
where 

address is an address value. 

m_strip points to the first menu in the menu strip. 
m_ number is the number of the menu or menu item. 

This function will find the address of a menu item. 

Now that we've talked so much about all the details involved in creating 
a menu, Listing 3-16 shows the definition of a single menu in a window— the 
most basic situation. In this example nothing can be done with the menu 
except display it. Even merely noting selection must wait until we cover basic 
window-related input/output. The function CreateMesf) uses the IntuiText 
structure to create the text for each menu item. The process of the examples 
that follow is simple and straightforward: 

• First, we defined a list of three Menultem structures. 
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. We attached this Unked list to our menu structure usxng *. F.rstltem 
gram. 

, • .• 1 1B ("wion ol a menu in « window. This .hows ooly 

- *- a* a — — 

include <exec/types.h> 

include <1ntuUion/intintlon.h> n 
struct Window *Wind,*NoBorder; 



mai nO 

VoNG flags; ZARAGOZA 
SHORT x.y.w.h; 

UBfTE name [60]; p,„.t.M M {)- 
VOID delay.funcO ,0penALL() , CreateMes U , 

struct Menu Menul ; 
struct Menultem m0,m1,m2; 
struct IntuiText t0,t1,t2; 

OpenALLO; /* Add error checking */ 

;* ===========Set up a menu======== === * / 

C reateMes(StO,CHECKWIDTH + 2.0. "Choice 0"); 

n0.NextItem=Sm1 ; 
m0.LeftEdge=5; 
«0.TopEdge=0; 
n0.Width=100; 

mo! IF lags=CHECKIT | CHECKED | ITEMTEXT | HIGHCOMP | ITEMENABLED; 

mO.Mutua LExc lude-NULL; 

m O.ItemFiU=<APTR)StO; 

mO.SelectFi LL=NULL; 

mO.Command=NULL; 

mO.SubItem=NULL; 

CreateMes<&t1.CHECKWIDTH + 2,0,"Choice V); 

ml .Nextltem=8m2; 
ml .LeftEdge=5; 
m1.TopEdge=10; 
m1.gidth=100; 

ml " ptags=CHECKIT | ITEMTEXT | HIGHCOMP | ITEMENABLED; 
m1.MutualExclude=NULL; 
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Listing 3-16. (cont.) 



ml .ItemFi I L = (APTR)St1 ; 
ml .SelectFi I L=NULL; 
ml . Command=NULL; 
ml .SubItem=NULL; 

CreateMes (&t2,CHECKUIDTH+2,0 f "Choice 2"); 

m2.NextItem=NULL; 

m2.LeftEdge=5; 

m2.TopEdge=20; 

m2.Width=100; 

m2.Height=20; 

m2. F lags=CHECKIT | ITEMTEXT | HIGHCOMP | ITEMENABLED; 

m2 .Mutua LExc lude=NULL; 

m2. ItemFi I l=(APTR)&t2; 

m2. SelectFi ll=NULL; 

m2. Command=NULL; 

m2.SubItem=NULL; 

Menul .NextMenu=NULL; 
Menul . LeftEdge=0; 

Menul .TopEdge=0; | 
Menul .Width=200; 
Menul .Height=100; 

Menul . F lags=MENUENABLED; , 
Menul .MenuName="My First Menu"; 

Menul .Fi rstItem=SmO; 1 

I 



/* ======Open a borderless window======*/ 

x=y=0; 
w=640; 
h=200; 

flags=ACTIVATE | BORDERLESS; 

NoBorder=(struct Window *)make_window(x ,y,w, h, NULL, f lags) ; 



/* ======Open a plain window===== */ 

strcpy(name, "Plain Window "); 

x=y=20; 

w=300; 

h=100; 

f lags=ACTIVATE; 

Wind=(struct Window *)make_wi ndow(x,y,w, h, name, f lags) ; 
/* ==============0pen up the menu===================== */ 

SetMenuSt ri p (Wi nd , SMenul ) ; 
/* ======oelay for a bit to show off the wi ndows====== */ 
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Listing 3-16. (cont.) 



delay_func(100) ; 

/* =========Close down the windows in order========*/ 

ClearMenuStrip(Wind) ; 
CloseWindow(Wind) ; 
delay_func(10) ; 
CloseWindow(NoBorder) ; 



VOID CreateMesCx, left, top, mesg) 

struct IntuiText *x; 

SHORT Left, top; 

UBYTE *mesg; 

i 

x ->FrontPen=0; 
x->BackPen=1 ; 
x->DrawMode=JAM1 ; 
x-> Left Edge= Left ; 
x->TopEdge=top; 
x-> iText Font=NULL; 
>->IText=mesg; 
,->NextText=NULL; 

> 




. We had to define two linked lists of Menultem structures and attach 

them to the menu structure. 
. We had to create a linked list of menu structures. 

Listing 3-17. Creation of two menus in a window. This shows 
only the creation and display, nothing is done wrth the 

menu items. 



^include <exec/types.h> 
include <intuition/intuition.n> 

struct Window *Uind,*NoBorder; 

nai nO 
C 

ULONG flags; 
SHORT x,y,w,h; 

Sro^"'?2ic<).Op.nALL().Cr..t.N..().Cr..t.It..<> S 
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Listing 3-17. (cont.) 



struct Menu Menu1,Menu2; 
struct Menultem m0,m1 ,m2,x0,x1 ; 
struct IntuiText t0,t1 ,t2,xt0,xt1 ; 

OpenALLO ; 

/* ===========Set up a nenu===========*/ 

CreateMes(8tO,CHECKWIDTH+2,0, "Choice 0"); 
C reatel tem(&t0, &m0 , Sm1 ,5,0, CHECKED); 

CreateMes(8t1 ,CHECKUIDTH+2,0, "Choice 1"); 
CreateltemCStl ,8m1 ,8m2,5,10,0> ,• 
CreateMes(&t2,CHECKUIDTH+2,0,"Choice 2"); 
CreateItem(8t2,8m2,NULL,5,20,0); 

Menul .NextMenu=8Menu2; 

Menul . LeftEdge=0; 

Menul .TopEdge=0; 

Menul .Width=200; 

Menul .Height=100; 

Menul .Flags=MENUENABLED; 

Menul .MenuName="My First Menu"; 

Menul .Fi rst Item=8m0; 

/* =======set up a second menu==========*/ 



CreateMes(8xtO,CHECKWIDTH+2,0, "Choice 1") ; 
Createl tern (8xt0, 8x0, 8x1 ,5,10,0); 

CreateMes(8xt1 , CHECKWIDTH+2,0, "Choice 2"); 
Createltem(8xt1 ,8x1 .NULL, 5, 20,0) ; 

Menu2.NextMenu=NULL; 
Menu2.LeftEdge=220; 
Menu2.TopEdge=0; 
Menu2.Width=200; 
Menu2.Height=100; 
Menu2.Flags=MENUENABLED; 
Menu2.MenuName="My Second Menu"; 
Menu2.Fi rst Item=8x0; 



/* ======0pen a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

flags=ACTIVATE| BORDERLESS; 

NoBorder=(struct Window *)make_window(x, y.w.h, NULL, f lags) ; 
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Listing 3-17. (cont.) 



/* 



====0pen a plain window====- */ 



strcpy(name, "Plain Window ") ; 

x=y=20; 

w=300; 

h=100; 

Wmd'csSruc^wlndow *)make_window(x,y.w,h, name. flags); 
1+ == ============0pen up the menu====== ======== *^ 

SetMenuSt ri p (Wi nd , &Menu1 ) ; 

/* ======Delay for a bit to- show off the wi ndows====== */ 

delay_func(100); 

/* =========Close down the windows in 0 rder========*/ 

ClearMenuStrip(Wind) ; 
CloseWindow(Wind) ; 
delay_func(10); 
CloseUindow(NoBorder) ; 



o 

Q 1> 



VOID CreateMesCx, left, top, mesg) 
struct IntuiText *x; 
SHORT left, top; 
U8YTE *mesg; 

I 

x->FrontPen=0; 
x->BackPen=1 ; 
x->DrawMode=JAMl ; 
x->LeftEdge=left; 
x->TopEdge=top; 
x-> IText Font=NULL; 
x->IText=mesg; 
x->NextText=NULL; 

} 



VOID createltem(name,i tern, next, left, top, flags) 

UBYTE *name; 
USHORT left, top; 
ULONG flags; 

struct Menultem *item,*next; 

/« This function will set up a simple Menultem structure */ 
I 

item->NextItem=next; 
item->LeftEdge=left; 
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Listing 3-17. (cont.) 



i tem->TopEdge=top; 

item->Width=100; 

item->Height=10; 

item->Flags = CHECKIT| ITEMTEXT | HIGHCOMP | ITEMENABLED | f lags; 

i tem->MutualExc lude=NULL; 

item->ItemFi I l=(APTR)name; 

item->SelectFi ll=NULL; 

i tem->Command=NULL; 

item->SubItem=NULL; 



Listing 3-18 puts menus in two windows. This requires that we create 
two disparate linked lists of menus and make two calls to SetMenuStripf ), as 
well as two to ClearMenuStrip. 

Listing 3-18. Creation of menus in two windows. This shows 
only the creation and display, nothing is done with the 
menu items. 



^include <exec/types . h> 

# include <intuition/intuition.h> 

struct Window *Wind,*NoBorder; 

mainO 
{ 

ULONG flags; 
SHORT x,y,w,h; 
UBYTE *name; 

VOID delay_func() ,0penALLO ,CreateMesO , CreateltemO ; 
struct Menu Menul ,Menu2,Menu3; 
struct Menultem m0,m1 ,m2,x0,x1 ,p0,p1 ; 
struct IntuiText tO.tl ,t2,xt0,xt1 ,pt0,pt1 ; 

OpenALLO ; 

/* ===========Se t up a menu===========*/ 

CreateMes(8tO,CHECKWIDTH+2,0, "Choice 0") ; 
Createltem(8t0, 8mO, 8m1 ,5,0, CHECKED) ; 

CreateMes(8t1 ,CHECKWIDTH+2,0, "Choice 1") ; 
Createltem(8t1 ,8m1 ,8m2,5,10,0) ; 

CreateMes(8t2,CHECKWIDTH+2,0, "Choice 2") ; 
CreateItem(8t2,8m2,NULL,5,20,0); 

Menul .NextMenu=8Menu2; 
Menul . LeftEdge=0; 
Menul .TopEdge=0; 
Menul .Width=200; 
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Listing 3-18. (cont.) 



Menul .Height=100; 

Menul .Flags=MENUENABLED; 

Menul .MenuName="My First Menu' ; 

Menul .FirstItem=&mO; 

/+ =======Set up a second menu==========*/ 



CreateMes(&xt0,CHECKWIDTH+2,0, "Choice 1"); 
Createltem(&xt0,&x0,&x1 ,5, 10, CHECKED) ; 

CreateMes(&xt1.CHECKWIDTH+2 0. "Choice 2") ; 
CreateItem(Sxt1 ,4x1 .NULL. 5, 20,0) ; 

Henu2.NextMenu=NULL; 

Menu2.LeftEdge=220; 

Renu2.TopEdge=0; 

Henu2.Width=200; 

Renu2.Height=100; 

Henu2 . F lags=MENUENABLED; 

«enu2.MenuName="My Second Menu ; 

Menu2.FirstItem=&xO; 



/* =======And a thi rd==========*/ 



CreateMes(&pt0,CHECKWIDTH + 2 0 "Choice 1"); 
CreateItem(Spt0,Sp0.Sp1,5,10,0); 

CreateMes(8pt1.CHECKWIDTH+2,0, "Choice 2"); ■ 
CreateItem(&pt1,Sp1.NULL,5,20,0); 

Menu3.NextMenu=NULL; 

Menu3.LeftEdge=0; 

Menu3.TopEdge=0; 

Menu3.Width=200; 

Menu3.Height=100; 

Menu3 . F lags=MENUENABLED; 

Menu3.MenuName="Second Window Menu , 

Menu3.Fi rstltem=&p0; 



/* ======0pen a borderless wi ndow======*/ 

name="A Window without Borders"; 

x=y=0; 
w=640; 
h=200; 



/* ======0pen a plain window====- *' 
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name="Window: 2 Cents Plain"; 
x=y=20; 
w=300; 
h=100; 

f lags=ACTIVATE; 

Wind=(struct Window *)make_window(x, y,w,h, name, f lags) ; 
/* ==============0pen up the menu===================== */ 

SetMenuStrip(NoBorder,&Menu3) ; 

SetMenuStrip(Wind,SMenu1) ; 
/* ======Delay for a bit to show off the wi ndows====== */ 

delay_func(100); 
/* =========c lose down the windows in order========*/ 

ClearMenuStrip(Wind) ; 

ClearMenuStrip(NoBorder) ; 

CloseWindow(Wind); 

delay_func(10) ; 

CloseWindow(NoBorder) ; 

> 

IntuitionBase=(struct IntuitionBase *) 

OpenLibrary ("intuition. library", INTUITION_REV) ; 

if (Intuit ionBase==NULL) 
ex it (FALSE); 

> 

VOID CreateMes(x, left, top, mesg) 
struct IntuiText *x; 
SHORT left, top; 
UBYTE *mesg; 

{ 

x->FrontPen=0; 
x->BackPen=1 ; 
x->DrawMode=JAM1; 
x->LeftEdge=left; 
x->TopEdge=top; ZARAGOi A 

x->ITextFont=NULL; 
x->IText=mesg; 
x->NextText=NULL; 

} 

VOID C reat el t em (name, it em, next, left, top, flags) 
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Listing 3-18. (com.) .MA^ 



UBYTE *name; 
USHORT Left, top; 
ULONG flags; 

struct Menultem *item,*next; 



ZERO 



/* This function will set up a simple Menultem structure */ 
{ 

item->NextItem=next; 
item->LeftEdge=left; 
i tem->TopEdge=top; 
item->Width=100; 

i tem->F Lags=CHECKIT | ITEMTEXT | HIGHCOMP | ITEMENABLED | f lags; 

item->MutualExclude=NULL; 

item->ItemFi U=(APTR)name; 

item->SelectFi ll=NuLL; 

item->Command=NULL; 

item->SubItem=NULL; 



There are still more things that you can do with menus. Some of these 
are very basic, such as getting input from them. Some are more drama tl c-for 
example, using graphics techniques to create, on screen menus. 



Requesters 

Intuition offers us another menu-like faculty for entering values: the re- 
Sr Whenever a program needs a value from the user, a requester is 
cS for Tnis object halts the operation of its application and waits for a 
repry This isin contrast to the more passive menu, whose calling sequence is 
completely under the control of the user. The user must exphcitly cafl he 
mZ b y moving the mouse cursor to the proper position and pushing the 
Tper buttons. More importantly, a user can leave the menu without enter- 
ETWOfag i*o the P-gram-without making a choice A requite* m 
c^trast, demands input. Even requesters that can be exphcitly controlled by 
the user must be satisfied once they are called. 

Requesters screen locations are more flexible than menus and Imj be 
u=ed for some menu activities to greater effect. A menu must be at the top of 
th screen in the title bar. It is detached from its enclosing window and, in a 
™Sed display containing many windows, could even confuse the user A 
~ter appears in its associated window and, in fact, can be placed any- 
w^thto this enclosed space. Because of this, a requester can be placed 
near an object that it directly affects: a request for a color 
drawing, a frequency input adjacent to the display of its waveform. The effect 
"e dramatic and more appropriate to the complex displays typical of 
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large programs— particularly those that take advantage of the Amiga's com- 
plex support software. 

A requester is defined by its system defined structure. 

struct Requester { 

struct Requester *OlderRequest; 

SHORT LeftEdge.TopEdge, Width, Height RelLeft .RelTop; 
struct Gadget *ReqGadget; 
struct Border *ReqBorder; 
struct IntuiText *ReqText; 
USHORT Flags; 
UBYTE BackFi In- 
struct ClipRect ReqCRect; 
struct BitMap *ImageBMap; 
struct BitMap ReqBmap; 

>; 

As the structure definition shows, much of the power of this object 
comes from its interaction with the graphics subsystem. The system main- 
tains a linked list of requesters in order of appearance. This supports the 
nesting of these objects that is a feature of Intuition. OlderRequest refers to 
this activity and is set accordingly by the operating system. Width and 
Height define the limits of the box that frames the requester display. This 
must be big enough to contain all of the text and non-text objects that will be 
used to create the object. The requester box can be as large as the window- 
but no larger— or arbitrarily small. 

The positioning of the requester box refers to two sets of values. If the 
requester is to be placed in a fixed position within the window, then the fields 
LeftEdge and TopEdge will set this coordinate. However, if you initialize 
RelLeft and RelTop instead, the requester box will be positioned near the 
current position of the cursor. These two fields will set the offset. It is also 
necessary to set the POINTREL flag in the Flags field. It should be noted 
that RelLeft and RelTop are advisory; if the offsets specified would place the 
requester outside the window, the actual values are ignored and it is placed as 
close to them as is possible. The rest of the fields refer to the requester's 
interaction with the graphics subsystem. 

Before leaving the subject of requesters, there is one useful function that 
is appropriate to discuss here: AutoRequestt ). This function automatically 
creates and installs a boolean requester— one that seeks a yes or no answer. 
These boolean objects account for a large number of incidents of this data 
type. The general form of AutoRequestt) is: 

AutoRequest Cw_ptr,b_text,p_text,n_text,p_f lags, n_f lags, width, height ); 
where 

w_ptr points to a window. 

b_text points to a character string that holds the characters to be 
printed in the body of the requester. 

p_text is a pointer to the text associated with the positive response. 
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n_text is the message associated with the negative response. 
p_flags and n_flags are IDCMP flags, 
width and height specify the size of the requester box. 
This function will automatically create a requester for an application. 
Listing 3-19 shows an example that creates and opens a simple boolean 
requester using the AutoReauestf > function. Again, we used the CreateM es<) 
function to produce the three IntuiText messages necessary for the requester 
initialization: 

• One to explain what the requester wants 
. One to describe the positive choice 
. One to describe the negative 

Width and Height are set at 250 and 100 respectively. We set no special 
flags in this object. Requester input, like menu input must be through the 
normal I/O channels. 

Listing 3-19. Creation of a very simple requester using the 

AutoReque st( ) function. 

^include <exec/types.h> 

#inc Lude <intuition/intuition.h> 

struct Screen *Scrn; 

struct Uindow *wind0,*wind1 ; 

mainO 
< 

ULONG flags; 
SHORT x,y,w,h,d; 
USHORT mode; 
UBYTE *name,c0,d; 

VOID delay funcO .OpenALLO .CreateMesO ; 
struct IntuiText prompt, yprompt , nprompt ; 

OpenALLO; 

/* ======0pen a hi -res custom screen==== */ 

name="Requests Now Being Taken"; 

y=0; 

w=640; 

h=200; 

d=3; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h.d f c0,c1, mode, name), 

/* =======0pen a wi ndow========== ==== * / 
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Listing 3-19. (cont.) 



name="Ui ndow 1"; 

x=20; 

y=20; 

w=400; 

h=150; 

f lags=ACTIVATE| WINDOWS IZING|WINDOUDEPTH|WINDOWDRAG| 

WINDOWC LOSE | SMART_RE FRESH; 

c0=-0x01 ; 
c1=-0x01 ; 

windO=(struct Window *) 

make_wi ndow (x,y,w,h, name, f lags, c0,c1 ,Scrn, NULL) ; 

/* ======Bui Id and display a requester====== */ 

CreateMes(8prompt,45,25,"Stop The Music!"); 
CreateMesCSyprompt ,3, 3, "Yes") ; 
CreateMes (Snprompt ,3 ,3 , "No") ; 

AutoRequest (windO.Sprompt ,&yprotnpt ,8nprompt , NULL, NULL, 250, 100) ; 

delay_func(100); 

/* =========c lose down the window then the screen========*/ 

CloseUindow(windO) ; 
CloseScreen(Scrn); 



VOID CreateMesCx, left, top, mesg) 
struct IntuiText *x; 
SHORT left, top; 
UBYTE *mesg; 

/* This will prepare a message for display as IntuiText */ 
{ 

x->BackPen=1;' ffQB^^ ^ 



x->DrawMode=JAM1 ; 
x->LeftEdge=lef 
x->TopEdge=top; 



g g B O 



x->IText Font=NULL; TARAGOZA 
x->IText=mesg; A A K 1* « w 

x->NextText=NULL; 

} 



Alerts 



Everyone who has programmed on the Amiga has come face to face with one 
version of the alert data object— the "Guru Meditation" box. Alerts are a 
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MouseX, MouseY are relative to the upper left corner of the current 
window. 




Seconds, Micros reports the current system clock. 
IAddress points to an object associated with the message. 
IDCMPWindow points to the window associated with the message. ^" 
SpecialLink is used by the system. 

The ExecMessage and SpecialLink fields are used by the operating 
system to manage and route the message. The other fields contain the infor- 
mation and values necessary to the calling application. 

The Class field indicates the IDCMP flag value that is being transmitted. 

The Code field is interpreted in terms of the class of the message. It 
contains special values such as a menu or Menultem number. In the case of a 
RAWKEY event, it contains the generated code value. 

The Qualifier field is set by the input device and is also useful for 
RAWKEY situations. It indicates if the value sent has been accompanied by a 
qualifying event such as a SHIFT or CTRL key value. 

MouseX and MouseY report the coordinates of the cursor relative to the 
upper left-hand corner of the window. 

The Seconds and Micros fields contain the current time; this can be 
evaluated to give the date as well. 

Iaddress contains the address of an object significant to the message. 

IDCMPWINDOW is the window address for the message. 

By interpreting these fields, an application can interpret the IDCMP j 
stream. 

The events that generate these IntuiMessages are set by the IDCMP 
flags. These include: 

• MOUSEBUTTONS to report on the status of the buttons on the 
pointing device. Both up and down events are recognized. The code 
field of the structure contains either SELECTDOWN, SELECTUP, 
MENUDOWN, or MENUUR The latter two are only reported if the 
RMBTRAP flag is set. Otherwise, Intuition deals directly with these 
two actions. 

• MOUSEMOVE causes a set of x and y values to be reported, 
indicating the movement of the mouse. This is dependent on either 
REPORTMOUSE or some gadget's FOLLOWMOUSE flag being set 
simultaneously. If DELTAMOVE is also set, this report is in the form 
of a change from last position and not as an absolute coordinate. 

Certain flags are associated with a gadget: 

• GADGETDOWN is reported under appropriate circumstances if the 
GADGIMMEDIATE flag has been set. Gadget reports require the 
setting of the RELVERIFY flag. 

• CLOSEWINDOW indicates that this system-defined gadget has been 
chosen. 
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There are two menu flags: 

f A Hp 

* • MENUPICK indicates the selection of a menu. The number of the 




item or sub-item chosen will be in the Code field of the IntuiMessage 
structure. 



• MENUVERIFY causes any MENUPICK operation to wait for 
completion, until the application has responded to the message 
requesting it. All windows with this flag set must respond before 
operation can continue. Only the active window can cancel menu 
operations. 

The requester flags are: 

• REQSET reports the first requester open in a window. 

• REQCLEAR reports the last requester cleared; it is the complement 
to REQSET. 

• REQVERIFY, like its menu counterpart holds a requester pending 
until a reply from the application is received. Only the first requester 
is kept waiting. 

Window information is also reported. 

• NEWSIZE indicates a resizing operation has been performed on the 
window. 

• REFRESHWINDOW sends a message, if a refresh operation is 
necessary. This is only valid when SIMPLE _REFRESH or 
SMART_REFRESH have also been set. 

• SIZEVERIFY halts a sizing operation until the application signals it 
to continue. 

• ACTIVEWINDOW and INACTIVEWINDOW send a report, 
indicating that a window has gone into one of these states. 

Miscellaneous flags include: 

• RAWKEY sends unprocessed keycodes from the keyboard. These 
values are found in the Code field of the structure. 

• NEWPREFS sends a report indicating that the system preferences 
have been altered. A call to GetPrefsO will return the new values. 

• DISKINSERTED and DISKREMOVED indicate when these disk- 
oriented events have occurred. 

The verification functions operate in a different way from the other 
IDCMP functions. These send a message and then go to sleep via an Exec 
Wait() function. The activity that they request is halted pending a reply from 
the receiving task. The function will not proceed until this occurs. Caution is 
advised with this particular set of functions. There is potential for a system 
log jam or deadlock here, as tasks are held awaiting permission to complete. 
One way to ameliorate this problem is to create a monitoring task to manage 
such potential bottlenecks. 
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adds the text processing, editing, and formatting capabilities that we have 
come to expect from a computer terminal. Although this device exists outside 
of Irtuition, it can easily and smoothly interface with a window to produce a 
pleasing and convenient user interface. There are two ways to _ activate he 
console device: as an AmigaDOS device file or directly through calls to the 
console device. ^ ^ easiegt ^ ^ ^ gfa ft ^ 

involve the mo'st operating system overhead. Under AmigaDOS a console is 
treated as a kind of file-a byte stream. It is a sequential file of character 
strings with no further organization. Another qualification placed on this 
kind of console concerns the nature of the values. Raw, unproces sed input is 
one option, but well-behaved ASCII characters can be specified and are he 
rule Open)) is the AmigaDOS function call that sets up and starts the 
console A call to the complementary Closed will shut it down. Access 1S 
equally simple; it. too, is byte-oriented. The controlling task must supply a 
bufier to hold the input characters and a count of how many are going in or 
out Once these parameters are set and the console is opened, access is 
obtained through an appropriate AmigaDOS function caU: Read() o« 
This topic will be covered more fully in Chapter 4, which deals with the 
AmigaDOS operating environment. 

More flexibility is available by opening the console device directly, by- 
nassing AmigaDOS. To do this you must access the executive kernel. The 
first step is to allocate an IOStdReq structure, but in this case you need only 
initialize one of the fields. The io_Data field is set with a pointer to , tto 
window in question. A call to OpenDevicef) starts up the console device, 
connecting it to the specified window. IOStdReq is also set up for " c°mmum- 
caton between these two objects. At this point, text can be sent back and 
forth between the console and the window. 

To read from the console device, the following steps are necessary: 

. Set the io_Data field of IOStdReq to the address of a string buffer. 
. Set the io_Length field to the number of bytes expected in the 

transfer operation. 
. Finally, put the CMD_READ flag into io _Command. 
The read will be initiated by one of the I/O functions. DoIOf ) will trans- 
mit the request and then halt the task until that request is satisfied. 
SetdlOO, in contrast, will transmit the request and then return control to the 
caling program, even before that request has been satisfied. The field *o_ 
Actual will contain the number of bytes that were actually transferred. 

Text is written to the window in a similar way. The to Data field and ho 
length field are initiated as before, but this time the buffer contains the 
message to be sent. The io_Command field is set equal to nag CMD 
WRITE. Either DoIOO or SendlOO begins the request. Text will be written 
only in the non-border area of the window; it will never overwrite the border 
gadgets. A line that is too long to fit into the window space will be wrapped 
around to the next line. , . 

A program illustrating these functions and procedures can be found in 
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Listing 3-22. Here the function Send_Message() is created to properly initial- 
ize a IOStdReq structure and use it to send a message. 

Listing 3-22. Placement of text in a window using direct 
control of the console device. 



^include <exec/types . h> 

#i nc lude <i ntui tion/intui tion.h> 

struct Window *Wind,*NoBorder; 



mainO 
{ 

ULONG flags; 
SHORT x,y,w,h; 

VOID de lay_f unc () ,0penALLO ; 
OpenALLO ; 

/* ======open a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

flags=ACTIVATE | BORDERLESS; 

NoBorder=(struct Window *)make_window(x, y,w,h, NULL, f lags) ; 



/* ======Open some plain windows===== */ 

x=y=20; 

w=300; 

h=100; 

f lags=ACTIVATE; 

Wind=<struct Window *)make_window(x,y,w, h, "Window", flags) ; 
/* ===send a message to the window=== */ 
Send_Message(Wind,"I 'm seeing the world in a window"); 



j s B H O 
^aragoza 



/* ======Delay for a bit to show off the wi ndows====== */ 

delay_func(100); 
/* =========ciose down the windows in order========*/ 

delay_func(10) ; 

CloseWindow(Wind) ; 

delay_func(10); 
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Listing 3-22. (cont.) 



CloseWindow(NoBorder) ; 

} 



Serd_Message(to_window, message) 
struct Window *to_window; 
UBVTE *message; 
{ 

struct IOStdReq mesg; 

I* ===open the console in the window=== */ 

mesg.io Data=(APTR)to_window; 
OpenDevTceC'consoLe.devi ce",0,8mesg,0) ; 

/•» === sen d the message=== */ 

mesg.io_Data=message; 
m«sg. io_Length=-1 ; 
mesg.io_Command=CMD_WRITE; 
DoIO(Smesg) ; 

h ===tidy up=== */ 

C oseDevi ce(Smesg) ; 




Z B 11 «-» 



With the console device comes a full range of control sequences. These 
sequences offer special formatting and display options that allow the console 
device to mimic virtually any existing terminal, or allow the user to custom- 
ize to personal taste. In fact, the entire set of keyboard bindings-the values 
assigned to each keyboard code-can be altered by an application. 

Building an Intuition Library 

Our example programs up to this point have relied on our collection of sup- 
port files: i_sup.o. s_sup.o, and s_sup.o. With a little extra work, these files 
can serve a more general purpose and form the nucleus of a library of Intu- 
ition support functions that will further simplify the way that we write 
programs for this operating system. 

One important facility that is missing from our current collection of 
support functions is a set of Intuition i/o operations. It would be useful to 
be able to open a window, collect keyboard input through it, as well as 
sending our own messages out its display. What would be particularly 
useful is a pair of functions that would handle the details for us much as. 
print f( ) and scanf( ) handle the details of formatting and data conversion.? 
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One solution to this program is found in Listing 3-23 which shows the 
contents of w_io.c. 

Listing 3-23. Window input/output support routines — w_io.c 



^include <exec/types . h> 
^include <intuition/intuition.h> 

#define EOLN 1 /* end of Line flag */ 

#define EOLW 2 /* end of window flag */ 

" #define BACK_SP 0x08 /* interesting keyboard events */ 
fldefine CARRIAGE_RET OxOD 

static struct IntuiMessage *msg,*GetMsg(> ; 

int Current_x,Current_y; 



/* wputsO first moves the cursor to the currect position, then writes the 
character. The current position is found in the variabLes 
Current_x and Current_y. */ 

void wputsCwindow, string) 
struct Window *window; 
char *string; 
{ 

Move (window->RPort , Current _x, Cur rent _y) ; 
Text (window->RPort , string, str I en (string) ) ; 

Current y+=8; /* move to the next position */ 

} 

/* 

wgetsO captures several interesting keyboard events occurring 
within the selected window. 

*/ 

wgets (window, st ring) 
struct Window *window; 
char *string; 
{ 

int flag=0; 
SHORT x,y; 

Move (wi ndow->RPort , Current _x , Current_y) ; 
Current_y+=8; 

for(;;) { 

Waitd « window->UserPort->mp_SigBit); 

whi Le((msg=GetMsg(window->UserPort))) < 

if (msg->Class == CLOSEWINDOW) { /* user wants to shut down window */ 
ReplyMsg(msg) ; 
f lag=E0LW; 
break; 
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Listing 3-23. (cont.) 



/* keyboard input */ 
/* set end of line flag */ 



user wants to erase characters */ 
/* can't backup beyond */ 
/* column one */ 



if(msg->Class == VANI LLAKEY) 
if(msg->Code == CARRIAGERET) 
ReplyMsg(msg) ; 
f lag=E0LN ; 
break; 

> 

else 

if(msg->Code == BACK_SP> < 

if (window->RPort->cp_x <= Current_x> 

break; 
string—; 

x=window->RPort->cp_x; 
y =window->RPort->cp_y; 
Move(wi ndow->RPort , x-8, y) ; 
Text(window->RPort," ",1>; 
Move (wi ndow->RPort , x-8 , y> ; 

/* simple character input */ 

else 

if (window->RPort->cp_x < window->Width-8) { 
♦string = msg->Code; 
Text (wi ndow->RPort , st ri ng , 1 ) ; 
stri ng++; 



ReplyMsg(msg) ; 

} 

»string='\0' ; 
if <f lag == EOLN) 

return EOLN; 
if (flag == EOLW) { 

CloseUindow(window) ; 

return EOLW; 

> 



/* signal end of line */ 
/* close window handier */ 



Z E 1 1 

Z A R A G 



Two complementary functions are defined in this file: 

. wputsO accepts a character string from the calling program and 

places it in the specified window. 
. wgetsl) will initialize its parameter string with the next line entered 
through its window. 
Both of these functions deal with character strings, but the same principles 
aDDlv to other kinds of output. 

WvutsO is the simplest of the two although it does depend on som 
system functions that won't be fully covered until Chapter 5. Textf) wJl wn 
tiTmEd text on the screen, while MoveO will fix the position for 
wTite Both are graphics-oriented system calls. It should be noted that ev 
The positioning of the imaginary cursor within the window u bemg hand! 
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by the program. The external variables, Current_x and Current_y contain 
the information necessary to accomplish this positioning. Using these vari- 
ables is the simplest way to handle the cursor when dealing with a single 
window. In the expression Current _y+ =8, the figure 8 is a constant value 
that refers to the font size: it will vary for other fonts. 

The input function wgets() is a much more complex collection of code. 
Here we set up an IDCMP port and are set to trap two different classes of 
events: 

• CLOSEWINDOW indicates that the user has clicked this particular 
gadget in the window border. 

• VANILLAKEY is a keyboard event. A basic or raw keycode that has 
been translated using the default keymap. A simple ASCII value. 

Another possibility is to look for a RAWKEY event and do the character 
conversion explicitly. A CLOSEWINDOW event will cause an immediate exit 
from the loop, a call to CLOSEWINDOW! ), and a return of an appropriate 
flag value. 

The VANILLAKEY event is further subdivided into three parts. If the 
user enters a carriage return, an end of line flag is set and this is returned to 
the calling function. If a user enters a backspace, the character is erased from 
the display. Note that positioning and erase are handled by the program and 
not by any operating system buffering routine. Furthermore, a check is made 
to ensure that the user does not backspace beyond the first column of input. 
With simple character input, the last code typed at the keyboard is entered 
into the string. This character is also echoed in the window. 

For the functions in Listing 3-23 to work properly, some adjustment to 
our earlier files must be made. Since even text is rendered by the graphics 
system within a window, we must alter the OpenAllf) function in i_sup.c. 
Now it must open the Graphics library as well as Intuition. This change is 
reflected in Listing 3-24. 

Listing 3-24. New Intuition support routines— i_sup.c 



#include <exec/types.h> 

#inc lude <intui t ion/ intuit ion. h> 

struct IntuitionBase *IntuitionBase; 
struct GfxBase *GfxBase; 

fldefine INTUITION^REV 33 /* set the revision number of Intuition */ 
fldefine GRAPHICS_REV 33 /* ...and the graphics revision */ 

/* OpenAUO sets up the intuition environment for the user. */ 

OpenAUO 
< 

IntuitionBase=(struct IntuitionBase *) 

OpenLi brary ("intuit ion. I ibrary", INTUITION_REV) ; 

i f ( Intu i t i onBase==NULL) 
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«xi t (FALSE) ; 

Gfxlase=(struct GfxBase *) 

OpenLibraryC'graphics. library", GRAPHICS_REV); 

if(6fxBase == NULL) 
eci t (FALSE); 

> 



It is also necessary to change the make. window* ) function in w_sup.c 
and to set the parameters of the IDCMPFlags field to the proper values. We 
have also made this window function serve another general purpose by add- 
ing a provision that allows it to work either with a custom screen or with 
workbench in Listing 3-25. 

Listing 3-25. The modified window support function— w_ sup. c 



^include <exec /types. h> 
^include <intuition/intuition.h> 



/* rake windowO will open a window in the specified screen and with the 
indicated characteristics. *•/ 



makt_window(x,y,w,h, name, flags. colorO.colorl, screen) 

SHOIT x.y.w.h; 

UBYTE *name, colorO.colorl ; 

ULOiG flags; 

struct Screen *screen; 

{ 

struct NewUindow NewWindow; 



^Window. LeftEdge=x; /• initialize a NewWindow object */ 

Ne lU i ndow . TopEdge=y ; 

Ne»Window.Width=w; 

NeuWi ndow . He i ght=h ; 

NeyWindow.Detai lPen=colorO; 

NewWindow. BlockPen=color1 ; 

NawW i ndow . T i 1 1 e=name ; 

^^^ilSn^s^LOSEWINOOWlVANILLAKEY; /* setup for keyboard input*/ 

if(screen == NULL) 
NewWindow.Type=WBENCHSCREEN; 

else { 1 
NewW i ndow . Type=CUSTOHSCREEN ; 
NewUi ndow . Screen=screen ; 

) 

NewUi ndow . F i rstGadget=NULL; 
NewWi ndow. CheckMark=NULL; 
NewWindow. BitMap=NULL; 
NewWindow. MinWidth=0; 
NewWindow. Mi nHeight=0; 
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NewWindow. MaxWidth=0; 
NewWindow.MaxHeight=0; 

return(0penWindow(8NewWindow)) ; /* return the address of the window */ 

> 



Finally, Listing 3-26 contains a simple driver program to test out our 
new library functions. In this program, we open a high resolution screen and 
a window inside it. Inside a loop, input is accepted from a window and is 
immediately echoed back. The program is continuous until the user closes the 
window by clicking on the Close Gadget. Note that the initial cursor position 
is set relative to the position of the new window. 

Listing 3-26. A program to test the window library functions. 



#include <exec/types.h> /* include the support header files */ 
#include <i ntui t i on/ intuit ion. h> 

#define EOLN 1 /* end of line flag */ 

tfdefine EOLW 2 /* end of window flag */ 

Sdefine BACK_SP 0x08 /* interesting keyboard events */ 

tfdefine CARRIAGERET 0x00 

struct Window *wind; 
struct Screen *Scrn=NULL; 

extern Current_x,Current_y; 
void wputsO; 
ma i n ( ) 
{ 

ULONG flags; 
SHORT x.y.w.h.d; 
USHORT mode; 
UBYTE *name,c0,c1 ; 
char string[80]; 
OpenAUO; 

/* ======0pen a Hi Res Custom Screen==== */ 

name="High Resolution Screen"; 

y=0; 

w=640; 
h=400; 
d=3; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) make_screen(y,w,h,d,cO, d .mode, name) ; 



FORMAT 
ZERO 

ZARAGOZA 



in 



klsing Intuition 
i 



Listing 3-26. (cont.) 



/* =======And a Window= 



FORMAT 
ZERO 

ZARAGOZA 



name="Window"; 
x=20; 
y=20; 
w=300; 
h=100; 

flags=ACTIVATE|WINDOWCL0SE|WINDOWSIZING|WINDOWDEPTH| 

WINDOWDRAG|SM ART_REFRESH; 

c0=-0x01 ; 
d=-0x01 ; 



wind=(struct Window *) make.wi ndow(x,y,w,h, name, f Lags, cO,CI ,Scrn) ; 

Current_x=wind->BorderLeft+1; /* set initial cursor position */ 
Current _y=wind->Bo rderTop+7; 

while((wgets(wind, string)) != EOLW) /* loop until the user says stop */ 
wputs(wind, string) ; 



CloseScreen(Scrn) ; 



Not only do these files contain useful functions and routines that will I 
help us in our day-to-day programming, but they also serve as a model for 
dealing with the complexity of Intuition in a reasonable manner. By using the 
separate compilation facility of C, we can easily manage the complex data 
objects which are necessary to get full benefit from the powerful hardware. 



A Final Note on Programming Style 

The programs in this chapter-as well as those in the rest of the book-were 
designed primarily to illustrate the elements of the Amiga software environ- 
ment. Our purpose is to illustrate the methods by which a programmer can 
access each subsystem and make it perform. 

In order to enhance the tutorial nature of each listing, efficiency ana 
explicit error checking are sacrificed for clarity of expression; to include it 
would have obscured the sometimes intricate methods required by this com- 
plex software system. However, the reader should not assume that such 
considerations, particularly error checking-are in some way optional. On the 
Amiga, with its multitasking and lack of hardware memory management, it is 
vital to capture error conditions and return allocated resources; to fail to do 
so will lead to programs that do not behave well in this sophisticated environ- 

^^Each time a library is opened, or a screen or window created, the system 
gives up some of its store of free memory to the object. When such objects are 
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no longer needed, this memory resource must be returned to be used by other 
executing programs. There is no mechanism to return this memory automati- 
cally; the programmer must ensure that his or her code performs this service. 
It is particularly important when an error condition occurs while several of 
these items are being opened. If a program fails, some means of graceful 
shutdown must be included that will ensure that previously created objects 
will also be closed down. 

Another question is one of efficiency. In order to emphasize the parame- 
ters of Intuition objects, we have declared appropriate structure variables 
and then explicitly made assignments to individual members. A more effi- 
cient way would be to declare and initialize these structures in one step; this 
is particularly attractive since many of these values do not change during the 
run of the program. The examples in our proposed user library conform to 
this latter rule. 

Listing 3-27 is another example of the program found in Listing 3-8; this 
one includes error checking as well as a more efficient structure. The reader is 
invited to compare the two programs and note their differences. 

Listing 3-27. An example of a complete program. 



^include <exec/types.h> 
#include <i ntui t i on/ intuit ion. h> 
//include <latti ce/dos.h> 

struct IntuitionBase *IntuitionBase; 
struct Window *make_wi ndowO ,*WindO,*Wi nd1 ; 
struct Screen *ScrO,*Scr1 ,*tnake_screen() ; 

char high_resL"]="High Resolution Screen", 
low_resl"]="Low Resolution Screen"; 

/(define ACT ACTIVATE /* shorten the flag values */ 

//define I_REV 33 

mainO 
C 

if ( CIntui t ionBase=(st ruct IntuitionBase *) 

OpenLi brary ("intuit ion. library", I_REV) )==NULL) 
exi t (FALSE) ; /* library failed to open */ 



/*=====open a hi -res custom screen======*/ 

if ((Scr0=make_screen(0,640,200,3,00,01 .HIRES, hi gh_res))==NULL) { 
CloseLibrary(IntuitionBase); /* close the library */ 

exi t (FALSE) ; /* gracefully exit program */ 

> 
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FORMAT 
ZERO 

ZARAGOZ A 



nr 

he Amiga has a traditional operating system, AmigaDOS, which 
JL works together with Intuition. The most important task of Ami- 
gaDOS is resource management, including not only the file management 
system, but the all-important multiprocessing system. In this chapter, we'll 
discuss the use of this operating system resource to create programs that run 
successfully in an environment with other executing processes. 



Multitasking 

Most large computers— in contrast to the ubiquitous microcomputer, which 
has become almost a fixture in our daily lives— are scarce resources. Ir. order 
to use them, you must schedule time, make a reservation for a terminal 
period, or even submit a program to be run. Every effort has been expended 
to wring the last bit of operating time out of them. To this end, these systems 
are invariably multitasking: they run more than one program at a time. 
Indeed, they are more than this; they are also multi-user, serving more than a 
single user at a time. 

Until recently, microcomputers have not been treated in quite the same 
way. Because of their origin as small, general purpose machines, many of 
these machines have correspondingly simple operating systems. Usually, they 
can run only a single program at a time. Attempts have been made to create 
an environment in which more than one program can be in memory, but even 
then only one of these programs is available to the user at any given time. 
Switching from one to the other can be quite awkward. 

The advantages of multitasking are obvious: an increased productivity 
in terms of number of tasks performed per unit of time. If I can run two or 
three programs at the same time on my computer, I can accomplish more 
than if I can only run one. The trade-offs may not be so obvious, however. It 
is not just that a multitasking operating system is more complex than a 
single-user system. If this were the only difference, we would have long ago 
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What is actually being transmitted when a message is sent between 
two operating system entities? How is this connection made? This can be 
confusing. The only thing that does any traveling is a memory address. 
When you send a message from process A to device B, you create the 
message structure in that part of memory allocated to A and then pass a 
pointer to this structure to B. You are implicitly giving B the means and 
the right to access and probably change part of As memory. As a result, it 
is important that A not alter the structure until B signals that it has 
received the message. Nothing has been transmitted in the sense of a tele- 
phone line or a radio signal— a common but misleading metaphor used to 
explain message passing systems— just a reassignment of values, in this 
case, address or pointer values. 

A port address is frequently sent as part of a message. This is the reply 
port and it has a specific function to fulfill. The receiving entity-process or 
device-must tell the sender that the message was received. This acknowledg- 
ment is directed to the reply port found in the message structure. However, it 
is also possible and sometimes desirable to have a port that is publicly availa- 
ble. This is accomplished by giving the port a name which can later be 
accessed by other processes. This access is via the name field as part of the 
mp^Node field within the message port structure. 



Manipulating Ports and Messages 

The executive kernel contains a variety of system functions to manip 
ports and messages. You can add ports to the system and remove them using 
AddPortO and RemPortt). You can even use CreatePortl) to generate a brand 
new port- although this is not, strictly speaking, a system function, but is 
supplied as part of a library. The main interest in' this chapter, however, 
centers around the use of this message passing system: how to send and 
receive messages. 

The appropriate functions that allow you to use the facilities of the 
message passing system are listed below. 

port_id=FindPort (name) 
where 

port_id is a pointer to a port in the message system, 
name is a character string containing the port name. 
This function returns a pointer to a publicly accessible, named port 
PutMsg(port_id, message) 
where 

port _ id is a pointer to a port, 
message is a pointer to a message structure. 
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This function sends a message to the designated port. 

message=GetMsg(port_id) 
where 

port _ id is a pointer to a port. 

message is a pointer to a message structure. 

This function removes the next message on the port's queue. 

ReplyMsg(message) 
where 

message is a pointer to a message structure. 

This function returns a message to its point of origin. 

message=Wai tPort (port_id) 




where 

message is a pointer to a message structure. 



port _ id is a pointer to a port. 

This function suspends a calling process until a message is returned. 

PutMsgl) sends an initialized message structure to a particular 
port. The execution of this function is asynchronous: once it is called, any 
action performed by the operating system is done independently of the 
calling program. Since the Amiga has a multitasking operating system, 
responsibility for carrying through on this command is left to another 
process. The net effect is that control immediately passes to the next state- 
ment in line. 

Receiving a message is a more complex process. First, you have to know 
that a message has arrived at a given port. This requires an effort of synchro- 
nization between the sender and the receiver. The executive kernel has a 
signal allocation system to supply this synchronization. Furthermore, there 
is a high-level system that allows you to tap into it. The WaitPortf ) function 
puts the current task to sleep until a signal reaches its port. 

Once you know that a message is waiting for you, you still have to 
remove it from the port's queue; this is done with the GetMsgO function. 
Each call of this function removes the next message from the port. Note that 
these messages come off their queue in FIFO order; no other form of priority 
scheme can be applied to them. If there are no messages available, the value 
zero is returned. 

Finally, it is frequently, if not usually, the case that once a message is 
received, it must be acknowledged to the sender. This is accomplished using 
the Reply MsgO system call. Reply MsgO returns the message structure to the 
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port mentioned in the mm_ReplyP.ort of this original data structure. If the 
field is set to zero, no reply is expected. ReplyMsgO returns the original 
message, so it must not be called until that message has either been acted on 
or copied to a local buffer. By returning the message, you lose control of it. 
Messages are frequently reused by processes, so even if you retained its 
address, you would have no guarantee of the integrity of the values you 
found. Before a message is answered, it is the property of the receiver^ Of 
course, you must return the message as soon as possible, in order to speed up 
total system operations and increase process execution. 

A. kind of message receiving template is defined by the following code 
fragment; 

| gaitPort(Port); 

Whi le((message=GetMsg(Port)) !=NULL) C 
' ==>do something with the informations- 

ReplyMsg(message) ; 

} 

The basic command sequence appears over and over again in example 
programs. It illustrates the way you can use these system calls to produce 
coordinated message exchanges. Of course. PutMsgf) would be initiated from 
the original calling process. 

These four system functions-Pu tMsgO, GetMsgO, WaitPortl/, and 
ReplyMsgf )-are used in concert to access the message passing software 
made available by the executive kernel. They allow software objects not only 
to communicate with one another, but also to synchronize their operations. It 
must be emphasized that these are not the only system functions available to 
the user. These are the ones you will use to implement'and control multitask- 
ing under AmigaDOS, but several other iow-level subsystems are available to 
the advanced user. An entire I/O subsystem, for example, is built on top of 
this message passing facility; we have already seen examples of this m the 
earlier chapter on Intuition, particularly in the discussion of wmdow input 
and output. The next step is to relate messages, ports, and processes. A 
process, as defined so far, is an independent piece of program code, loaded 
into memory- It must have some way of communicating with other processes 
and the outside world. The message passing subsystem supplies this venue. 
This capability is an important constituent of the Amiga's multitasking capa- 
bility. 

AmigaDOS 

Of the three semi-autonomous operating environments available on the 
Amiga-the executive kernel. Intuition, and AmigaDOS-it is the latter that 
you will be primarily concerned with in creating multitasking programs. 
Indeed, it is within AmigaDOS that the notion of a process is formed. These 
other two operating systems lend support and background services, but the 
tools needed to create a multiprogram environment are found in AmigaDOS). 
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The executive kernel supplies the underlying software support for pro- 
cess creation. It defines the message passing system and also a management 
system for low-level tasks. Each task is a software object; that can be created 
or removed by the operating system. These tasks can be further manipulated, 
and themselves represent executable code modules. However, a task is not a 
process; it is a much more primitive entity. These are only the barest begin- 
nings of a multitasking system. 

An AmigaDOS process is, like most Amiga software objects, defined by 
* a C structure definition: 

struct Process { 

struct Task pr_Task; 
struct MsgPort pr MsgPort; 
WORD pr_Pad; 
BPTR pr_Seglist; 
LONG pr_TaskNum; 
BPTR pr_StackBase; 
LONG pr~Result2; 
BPTR pr_CurrentDi r, 

pr_CIS, 
pr_COS; 

APTR pr_ConsoleTask, 

pr_Fi LeSystemTask; 
BPTR pr~CLI; 
APTR pr_ReturnAddr, 
pr_PktWai t , 
pr WindowPtr; 

>; 

This is a long and complex definition, but fortunately, most of these 
fields are set by the AmigaDOS system calls that you make to set up and use 
a process. One important thing that you can see immediately is that a process 
has a message header for access to the system of ports and messages. Also 
note that a process is also part of the task manipulation system; entry here is 
via the Task structure at the very beginning of the definition. 

The remaining fields are, for the most part, straightforward, if not 
always obvious. The pr_SegList points to the memory locations where the 
process code currently resides. pr_StackSize indicates the number of bytes in 
this resource. Process identification is through pr_TaskNum; this relates the 
process to a task number relative to the calling CLI. There are also hooks to 
the current disk directory (pr_CurrentDir), the standard input and output for 
this process (pr_CIS and pr_COS), as well as pointers to the various subsid- 
iary and support processes and functions. These fields are rarely manipulated 
directly by a user process. 

The tasking system is responsible for the process once it is in memory. 
It manages the CPU and other resources. This system takes primary respon- 
siblity for scheduling and moving between the various states associated with 
an executing process. One of its primary jobs is to switch between the various 
competing processes, giving each one a quantum of access to the system and 
then moving to the next. It is this switching that allows many programs to 
run simultaneously. 
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Although the tasking subsystem is directly available to the programmer 

£§g2ES££33S25 

a prtessTe lost. In a complex application this can pose a problem. 
Calling AmigaDOS 

that we are interested in is: 
DateStamp(d_ptr) ; 

Once called, this function will accept a pointer to .MOT structure; 
it will fill this structure with current values: 

d_ptr->ds_Days indicates the number of days since 1 January 1978. 
d_ptr->ds_Minute is the number of minutes since midnight. 
d_ptr->ds_Tick is the number of ticks since the beginning of the 
minute. 

This latter measure is potentially confusing; it refers to a measure jtihjfc 
divides a single minute. In the case of the Amiga, there are 50 ticks in a single 
minute. 

Listing 4-1. DateStamp AmigaDOS call. 



^include <exec/types.h> 
flinclude <exec/nodes . h> 
#incLude <exec/lists.h> 
//include <exec/libranes.h> 
^include <exec/ports.h> 
//include <exec/interrupts.h> 
^include <exec/io.h> 
^include <exec/memory .h> 
^include <libraries/dos.h> 
^include <libraries/dosextens.h> 
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Listing 4-1. (cont.) 



mai n () 

struct DateStamp v; Z ARAGOZ A 

DateStamp(Sv) ; 



ZERO 



pHntfO'days (since 1/78) jij^/J-JHSSj;), 

printf ("minutes (since ■^night).......XW\n .w.asmnuxi , 

printf ("ticks (from start of minute) .. -Xld\n ,v.ds_Ticio, 



DateStampf) is an example of an AmigaDOS system call. It does not 
directiy paVSpate in any multitasking, although it is an important function 
£to oZ r <S but it does serve to illustrate the calling sequence Remem- 
be toTt HsclL in Chapter 2. In calling AmigaDOS functions, you 
must Unk The source code to amiga-Ub rather than Ic.lib, and it is imperative 
S yof disable stack checking with the option. The complete explanation 
is found in Chapter 2. 
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If Intuition is the user interface, then the CLI or command interpreter 
is the programmer's interface. Most program developmen proceeds from 
this faSS TTY-like interface. Editors and compilers work from it, and it 
gtes^ceS to most system support utilities. The CLI is perhaps the 
fasiest environment within which to run programs. You have seen m Chap- 
er 3 the™ y details that must be attended to in writing applies . ions 
for Intuition, in the CLI, the program interface is familiar and straight- 

^ Any program that you run under these circumstances is really a daugh- 
ter Dro^ess to the CLI from which you begin. Such processes mhent input/ 
%£?£Lb and windows from the parent although they car ^open their 
own resources as well. These daughter processes are started up and the LLI 
g^ dormant until the executing process is finished; then fctakes con^ 
fgain. The same thing is true for processes spawned by other Presses 
within this environment. Process A begins process B, and then goes to sleep 
until process B is finished executing. . 

Sne way to accomplish this simple form of multiprocessing is to use the 
ExecuteO system call. The general form of this function is: 

Execute (st ring .input, output); 

Here, the function returns a boolean value to indicate whether or not it 
was successful. It takes as parameters: 
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• A. string indicating the name of the program to be run 

• Input and output streams to be used to display results 

If you set input and output to zero, the current assignments for these 
files is used. 

Listing 4-2. A simple example of the AmigaDOS Execute call. 



^include <exec/types.h> 
^include <exec/nodes.h> 
^include <exec/lists.h> 
/(include <exec/libraries.h> 
#include <exec/ports.h> 
^include <exec/interrupts.h> 
#include <exec/io.h> 
IKinclude <exec/memory .h> 
#include <libraries/dos.h> 
^include <l i brari es/dosextens . h> 

mainO 
{ 

ExecuteC'dir df1 :source",0,0) ; 

} 



A very simple use of Executed is illustrated in Listing 4-2. Here you 
have a main!) function whose sole purpose is to call this function to execute a 
dir command on a particular subdirectory. The function is set up so that it 
uses the current window as output; there is no input value. Listing 4-3 shows 
a slight variation on this same program. Here we call two different commands 
from mainf). We also program a delay into the program by reference to the 
Delay!) system call. This accepts a duration, measured in ticks, as a parame- 
ter and waits the specified time. 

Listing 4-3. A simple example of the AmigaDOS Delay call. It 
is used in conjunction with the Execute call. 



^include <exec/types.h> 
#incLude <exec/nodes.h> 
^include <exec/ Li sts . h> 
/(include <exec/libraries.h> 
#include <exec/ports.h> 
//include <exec/i nterrupts . h> 
//include <exec/io.h> 
//include <exec/memory .h> 
//include <libraries/dos.h> 
//include <Li brari es/dosext ens. h> 

mainO 
{ 



130 



Chapter 4 



Listing 4-3. (cont.) 



ExecuteC'dir df 1 :source",0,0) ; 

Delay(1500>; 

Execute<"info",0,0); 

} 



The Execute!) system function can be used in the manner illustrated in 
Listing 4-4. By passing the function an empty string, you can create a new 
interactive CLI just as if you had called NEWCLI from the command level. 
In order to accomplish this you must specify a window for the new CLI. The 
example does this with the declaration: 

struct FileHandle *wind; 

This filehandle type will be explained in greater detail in Chapter 9, 
when we turn our attention to the file management system. Accept it here as 
a designator for a new input window. By setting the final parameter to zero, 
the output stream will be associated with this new window. 

Listing 4-4. This program starts a new CLI, 

using the Execute! ) function. 



//include <exec/types . h> 
//include <exec/nodes.h> 
frinclude <exec/ 1 i sts .h> 
//include <exec/libraries.h> 
//include <exec/ports.h> 
//include <exec/i nterrupts . h> 
//include <exec/io.h> 
//include <exec/memory .h> 
//include <libraries/dos.h> 
#include <libraries/dosextens.h> 

struct FileHandle input; 

mainO 
< 

static char cmd []="", • 
Execute(cmd,8input,0) ; 
Delay(1500); 

> 
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Using Workbench To Start a Process 

You are now familiar with Workbench from the recent discussion of Intuition. 
The Workbench Screen is one of the standard screens that comes up in this 
user interface. In some ways, it is the primary standard screen, certainly the 
most commonly seen. But Workbench is also a system utility program that 
defines other operating environments. That's what we will explore here. 
Actually, Workbench defines two environments: 

1. The iconic interface that allows you to choose programs visually via 
the mouse and an Intuition screen 

2. An interface that allows you to start up programs as complete 
independent processes 

j It is this latter capability that is most interesting here, for you can tap it 

from the CLI interface, bypassing Intuition. Workbench allows you to create 
the most complete form of multiprocessing— totally independent executing 
processes. 

Before plunging into examples, consider what is necessary to set up an 
independent process: 

1. First, you must load the code that is to execute into the memory of 
the computer. 

2. Second, you must alert the system that you are starting up a new 
process. 

3. You must signal the loaded and initialized code that it can begin 
executing. 

The first of these requirements is self-evident. You cannot run anything 
until it resides in memory. Configuring code as a process involves taking care 
of all overhead that is necessary for the system to treat the program as a 
process. This includes activities such as putting the program in the process 
queue and initializing its process structure values. Finally, the code itself 
needs some kind of indication that all is well and that it can begin doing 
whatever it was meant to do. 

Loading program code into memory is controlled by two complementary 
AmigaDOS functions: LoadSegO and UnLoadSegf ). The first of these takes 
the object file produced by the compiler and linker and loads it into whatever 
free locations it finds in memory. It has the general form: 

segment_id=LoadSeg(f i Le_name) ; 

Segment _id points to the head of a chain of segments that contains the 
code, File _name is the name of the file as it appears in the disk directory. 
Note here that the program will not necessarily reside in contiguous memory 
locations. This is why the segment _id is a pointer to a linked list. Once you 
are finished with the program, you must remove it from memory and return 
its resources to the free memory pool. This is accomplished by: 

UnLoadSeg (segmented) ; 
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Segment _id points to a linked list of locations to be returned to the 
system. It is very important to perform these un-do operations. Under Ami- 
gaDOS, no automatic reclamation of resources is performed. If you forget to 
unload memory, it remains unavailable to the system. 

Now that you have your program code loaded, you need to turn it into a 
process. Do this with: 

process_id=CreateProc (proc_name,pri , segment _ id , stack) ; 

This system call takes the code that is stored under segment _id and 
" creates a new process. Pri sets the priority of the process. The value stack 
sets the size of this resource. Proc_name is a character string variable that 
contains a name for the process. CreateProcf ) returns a process _id which is 
of type struct Process. If the operation fails, zero is returned. 

CreateProcf) actually starts up the process. It puts in any necessary 
queues, does all the overhead necessary to start the process up, and enters 
the code at the first segment. This segment is expected to contain some 
initialization routine to get the program started. The easiest way to accom- 
plish this start-up task is to arrange your code so that it accepts a start-up 
message from its initiating task. Using the Workbench environment and, 
more specifically the Workbench start-up message, is a very convenient way 
to accomplish this. 

The Workbench start-up message is a software object defined by the 
structure WBStartup found in workbench/startup. h shown below. 

struct WBStartup { 

FORMAT 
Z E H O 

Z ARAGOZ A 

char *sm_TooLWindow; 
struct WBArg sm_ArgList; 

> 

where 

sm_ Message is an entry to the message passing system. 

sm_Process connects the start-up message to a process. 

sm_ Segment points to the memory resident code of a process. 

sm_NumArgs indicates the number of arguments being passed. 

sm_ToolWindow is a pointer to support window. 

sm_ArgList contains the arguments being passed in this message. 



struct Message sra_Message; 

struct MsgPort sm_Process; 

BPTR sm_Segment; 

LONG sm_NumArgs; 
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Many of these fields relate to the iconic interface. In our examples, we 
will only be using this structure as a start-up message and so will do the 
barest minimum of initialization. You should know that there is much more 
versatility built into this interface than we will utilize now. 

Listings 4-5 and 4-6 illustrate a simple process creation. The first pro- 
gram loads the object code from the second, creates a process, sends it a 
start-up message, and then sends it an additional message with more instruc- 
tions. The first process then goes to sleep until the second is finished. In 
Listing 4-6, the program receives the message, executes the request, and then 
sends a reply message back to the first. This example illustrates one of the 
simplest systems, where a process spawns another process. 

Listing 4-5. A simple process creation, using LoadSeg( ), 
UnloadSegl ), and CreateProd ). 



#include <exec/types.h> 

#include <exec/nodes.h> 

#include <exec/lists.h> 

^include <exec/libraries.h> 

#include <exec/ports . h> 

^include <exec/interrupts.h> 

^include <exec/io.h> 

^include <exec/memory . h> 

#incLude <libraries/dos.h> 

tfinclude <L i brari es/dosextens . h> 

^include <workbench/startup.h> 

extern struct Message *GetMsg(); 

extern int LoadSegO; 

extern struct MsgPort *CreateProcO ; 



struct P_Mess { 

struct Message message; 
char *title; 
int files[3]; 

>; 



V 



extern int stdin; 
extern int stdout; 
extern int stderr; 

struct MsgPort *NewProc; 
int NewSeg; 

mai nO 

struct Message *reply; 
struct Process *o_proc; 




struct WBStartup st; 
struct P_Mess pmes; 
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Listing 4-5. (cont.) 



struct MsgPort *o_rp; 

ifCinit proc("p1_test","New Process")==0) 
ExitO; 

o_proc=(struct Process *) Fi ndTask(O) ; 
o_rp=So_proc->pr_MsgPort ; 

make startup(Sst) ; 
PutMsg(NewProc,Sst); 

make_message(Spmes,"CON:100/10/320/150/New Process") ; 

PutMsg(NewProc,8pmes) ; 

WaitPort(o_rp); 

reply=GetMsg(o_rp) ; 
Uai tPort (o_rp) ; 
reply=GetMsg(o_rp) ; 

UnLoadSeg (NewSeg) ; 



i ni t_proc (f name , pname) 
char *fname,*pname; 
{ 

if <(NewSeg=LoadSeg(fname))==0) i 

printf ("Can't Create a SegmentW) ; 
return(O) ; 

} 

if ((NewProc=CreateP roc (pname, 0, NewSeg, 5000)) ==0) < 
printf ("Can't Create a Process\n") ; 
UnLoadSeg (NewSeg) ; 
return(O) ,- 

> 

returnd) ; 



make_startup(x,reply_port) 
struct WBStartup *x; 
struct MsgPort *reply_port; 

<; 

x->sm Message. mn_RepLyPort=repLy_port; 
x->sm_Message.mn Length=si zeof (struct WBStartup); 
x->smlMessage.mn_Node. Ln_Name="startup"; 
x->sm_ArgList=NULL; 
x->sm_TooLWindow=NULL; 

make_message(y,gist_of_it,reply_port) 
struct P_Mess *y; 
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Listing 4-5. (cont.) 



char *gist of_it; 

struct MsgPort *reply_port; 

{ y ->message.mn_ReplyPort=repLy port; 

y->message.mn Length=s vzeof (struct P Mes), 

y ->message . mn>de . ln_Name="pO_t est" ; 

y->titLe=gist_of_it; 

y->f i LesCO] = (int)stdin; 

y ->fi i eS [1] = (int)stdout; 

y ->files[2] = (int)stderr; 



returns process ideutification if ^ P"' '^XtTe p rocS it is e W to 
the lines: 

o_proc=(struct Process *)FindTask(0> ; 
o_rp=So_proc->pr_MsgPort ; 

The next step i, to utilize this information by passing some messages to 
cout.n the start-up message. There are 7'" P ™ ^'"^Vto "sStup". 

.» a G .i). ^ "^iS^JS^^SSi the 
iTa "—"message. FinaUy. you umo.d the 
new process segment. 
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Listing 4-6. A simple process, using LoadSeg( ), UnloadSeg( ), 
and CreateProcQ. This is the companion to pO_test.c. 



^include <exec/types . h> 
#include <exec/nodes . h> 
#include <exec/ Li sts . h> 
^include <exec/ I i brari es . h> 
ffinclude <exec/ports.h> 
rinclude <exec/interrupts.h> 
Hfinclude <exec/io.h> 
#include <exec/memory .h> 
^include <libraries/dos.h> 
#include <libraries/dosextens.h> 
#include <workbench/startup. h> 



extern struct Message *GetMsgO; 
extern struct Task *FindTaskO; 
extern struct FileHandle *0penO; 



struct P_Mess t 

struct Message Message; 
char *title; 
int fi lesC31; 

>; 

extern int stdout; 
extern int stderr; 



FORMAT 
'ZERO 
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mai n() 
{ 

struct P_Mess *pmes; 

struct MsgPort *cur_rp; 

struct Process *cur_proc; 

struct FileHandle *new_outp,*stdin; 

char chUOl ,*get_stringO ; 

cur proc=(struct Process *)FindTask(0) ; 
cur~rp=&cur_proc->pr_MsgPort; 



WaitPort(cur_rp) ; 



pmes=(struct P_Mess *) GetMsg (cur_rp) ; 



stdout=pmes->f i lesM 1 ; 



i f ( (new_outp=Open(pmes->ti t le, MODE.NEWF ILE) )==0) < 
ReplyMsg(pmes) ; 
exit(O); 

> 

else { 

stdout=(int)new_outp; 
stdi n=new_outp; 
printf ("enter anythi ng==>") ; 
get_string(stdin,ch) ; 
printf ("%s\n",ch); 
stdout=pmes->f i lesCI j ; 
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Listing 4-6. (cont.) 



Close(new_outp) ; 
RepLyMsg(pmes) ; 

] 

} 

char *get_string(fp, buffer) 
strict FileHandle *fp; 
char *buffer; 
{ 

int len; 

ler,=Read(fp, buffer, 39) ; 
bu1fer+=( len+1) ; 
*biffer='\0'; 

> 



Listing 4-6 contains a simple program. It, too, figures out the address of 
its own port and waits for a message from the parent process. Note that the 
activity of the start-up message has already been handled by the time these 
statements are executed. A reply has already been sent. This program is 
waiting for the second command message. Once the second message is re- 
ceived, it is executed by the statement: 

new_outp=Open(pmes->title,MODE_NEWFILE) ; 

This statement— embedded in an if statement— opens the window indi- 
cated in the character string pmes-> title. Although the new process does not 
inherit any I/O streams from the parent— it is a totally independent process— 
we do send over the stdin and stdout. Here we are creating a new set of I/O 
streams. Once we do this, we ask for some input from the keyboard, then 
return to the other process. 

The finishing code for this smaller process is correspondingly simple. We 
close the new window, reply to the command message, and then stop execu- 
tion. One final note— since we are using amiga.lib and not Ic.lib, it is neces- 
sary to create getstringf) in order to do simple input from a window. We do 
not have scanff) available to us in this particular library. 

The two remaining examples are variations on this first pair of pro- 
grams. Listing 4-7 contains a more realistic version of Listing 4-5; it uses 
AllocMemO to dynamically allocate memory and does some additional error 
checking. Listing 4-8 is, however, significantly different. Here we start up two 
independent processes from the parent. Each daughter process is given a 
slightly different command message. Both of these programs use the code in 
Listing 4-6 to produce child processes. 
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Listing 4-7. A more complex process creation, using 
LoadSeg( ), UnloadSeg( ), and CreateProc( ). 



^include <exec/types . h> 

flinclude <exec/nodes . h> 

^include <exec/ Li sts . h> 

#include <exec/libraries.h> 

#include <exec/ports.h> 

^include <exec/interrupts.h> 

#include <exec/io.h> 

^include <exec/memory .h> 

^include <l i brari es/dos . h> 

#include <L i brari es/dosextens . h> 

Sinclude <workbench/startup.h> 

extern struct Message *GetMsgO; 
extern int LoadSegO; 
extern struct MsgPort *CreateProc () ; 

struct P_Mess { 

struct Message message; 
char *title; 
int filesCSl; 

>; 

extern int stdin; 
extern int stdout; 
extern int stderr; 

struct MsgPort *NewProc; 
int NewSeg; 

ma i" n ( ) 
{ 

struct Message *reply; 
struct Process *o_proc; 

struct WBStartup *st; 
struct P_Mess *pmes; 

struct MsgPort *o_rp; 

ifCinit proc("p1_test","New Process")==0) 
ExitO; 

o_proc=(struct Process *)FindTask(0) ; 
o_rp=8o_proc->pr_MsgPort; 

if ((st=(struct WBStartup *) 

ALLocMem(sizeof (struct WBStartup) ,MEMF_CLEAR)) !=0) < 

make_startup(st) ; 
PutMsg(NewProc,st) ; 




3 L, R A □ 
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Listing 4-7. (cont.) 



} 

else { 

FreeMemCst , si zeof (struct WBStartup)) ; 
ExitO; 

> 

if ((pmes=(struct P Mess *) 

AllocMem(sizeof (struct P_Mess) ,MEMF_CLEAR) ) ! =0) < 

make_message(pmes, M CON:100/10/320/150/New Process"); 

PutMsg(NewProc.pmes) ; 

Uai tPort (o_rp) ; 

reply=GetMsg(o_rp) ; 
Wai tPort (o_rp) ; 
reply=GetMsg(o rp) ; 

> 

UnLoadSeg(NewSeg) ; 

FreeMem(pmes, si zeof (struct P_Mess) ) ; 
FreeMem(st, si zeof (struct WBStartup) ) ; 

} 

init_proc(f name.pname) 
char *fname,*pname; 
{ 

i f ( (NewSeg=LoadSeg (f name) )==0) { 

printf ("Can't Create a SegmentXn") ; 
return(O) ; 

> 

if ((NewProc=CreateProc(pname,0,NewSeg,5000))==0) { 
printf ("Can't Create a Process\n") ; 
UnLoadSeg(NewSeg) ; 
return(O) ; 

> 

return (1 ) ; 



make_startup(x, reply_port) 
struct WBStartup *x;~ 
struct MsgPort *repLy port; 
{ 

x->sm_Message.mn_ReplyPort=repLy_port; 
x->sm_Message.mn_Length=si zeof (struct WBStartup) ; 
x->sm_Message.mn Node.Ln Name="startup"; 
x->sm_ArgList=NULL; 
x->sm_Too LWi ndow=NULL; 

} 

make_nessage(y ,gi st_of_i t , reply_port) 
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struct P_Hess *y; 

char *gist_of_it; 

struct MsgPort *reply_port; 

{ 

y->message.mn_ReplyPort=rep ly_port ; 
y->message.mn_Length=si zeof (struct P_Mes) ; 
y->message .mn_Node. Ln_Name="pO_test"; 
y->t i t Le=gi st_of _i t ; 
y->fi lesCO]=(int)stdin; 
y->fi lesC1]=(int)stdout; 
y— > f i les[2] = (int)stderr; 

> 



Listing 4-8. The creation of two processes. 



^include <exec/types . h> 
#include <exec/nodes . h> 
#include <exec/ L i sts . h> 
^include <exec/ L i brari es . h> 
^include <exec/ports . h> 
#incLude <exec/ i nt errupt s . h> 
#include <exec/io.h> 
^include <exec/memory .h> 
^include <l i brari es/dos . h> 
#inc Lude <tibraries/dosextens.h> 
#include <workbench/startup. h> 

extern struct Message *GetMsg(); 

extern int LoadSegO; 

extern struct MsgPort *CreateProc() ; 

struct P_Mess { 

struct Message message; 
char *title; 
int f i Les[3]; 

>; 
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extern int stdin; 
extern int stdout; 
extern int stderr; 



struct MsgPort *NewProc,*Proc1 ,*Proc2; 
int NewSeg,Seg1 ,Seg2; 

mainO 
{ 

struct Message *reply; 

struct Process *o_proc; 

struct WBStartup st1,st2; 
struct P_Mess pmes1,pmes2; 
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As you saw in Chapter 3, Intuition offers an interface system that is 
both intuitive to the user and simple to set up and use. In this 
chapter we will continue to explore the services offered by this window- 
oriented system. Here we will concentrate on the graphics facilities. Intuition 
makes it possible to create sophisticated displays with little more effort than 
it would take to set up a menu or gadget. 

In the course of the chapter, we will return to some of the Intuition 
topics covered earlier. There, we used relatively simple examples, because you 
did not yet have the capabilities to create a fully visual object. Once you 
understand the many graphics functions, however, you will be able to create 
truly striking menus, gadgets, and requestors. 

Finally, we will discuss the graphics functions found at the very core of 
the Amiga, in the ROM kernel. Intuition provides a convenient backdrop for 
exhibiting the full power of the graphics engine that is built into the Amiga 
hardware. You can do moves, draw lines and polygons, and do area fill at an 
amazing speed, because of the specialized graphics hardware. The specialized 
windows and screens that we briefly touched on in Chapter 3 will come into 
their own. 



Intuition-Supported Graphics Functions 

Intuition itself offers a useful selection of graphics functions. These are closely 
tied to its system of screens and windows, and support the auxiliary functions 
of menus, gadgets, and requestors. Although their main purpose is to manipu- 
late the Intuition environment, these functions are by no means restricted to 
this secondary role. Frequently, the roles seem to be reversed, and a window 
may be opened so that a picture can be rendered by the drawing routines. At 
other times, it is the drawing that is subservient to a menu or a requester. No 
special preparation is required to use these functions. Since they are supported 
by Intuition, they can be used by opening Intuition itself as well as the graph- 
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ics library. Intuition takes care of any initialization necessary, and opens the 
appropriate libraries, making these functions even more attractive. As you will 
shortly see, much can be done with just these functions. 

There are three kinds of graphics output associated with the Intuition 
graphics system. 

1. Borders are lines or polygons drawn on the display area. 

2. Images are pictures produced by altering the values of each pixel in 
the display area. 

3. IntuiText is a character display rendered in a supplied or user- 
customized font. 

The only apparent surprise in this list is the IntuiText object; however, a 
character display is really nothing more than a specialized picture. By treat- 
ing it as straight graphics, Intuition offers a flexibility that is not available in 
many, otherwise powerful microcomputers. For example, text may be dis- 
played in any font style you choose. This graphic treatment of text also 
facilitates the integration of traditional pictorial information in a document. 

There is consistency among these basic graphics outputs. Each one 
shares a common form of construction and a common set of functions. There 
is a unique structure associated with each form — border, image, and In- 
tuiText— yet there is a great similarity between these structures. The imple- 
mentation of each form is also similar: DrawBorderi ), Draw Image! '), and 
PrintlTextf ). Each of these functions produces a display according to its 
appropriate form, yet each is similar to the other, having the same kind of 
setup specifications and parameters. In fact these functions are so alike that 
if you know how to create one of these objects, you can create the others. Of 
course, each of these data structures can be indirectly created through one of 
the other Intuition objects, such as a menu. Here there is a greater diversity 
of method, but still the underlying data structures are similar. 

One final note before plunging into the definition and manipulation of 
Intuition graphics: with each of these objects, Intuition allows you to create a J 
string of similar objects that can be dealt with in a single function call. You J 
can create not only one Intuitext message, one set of lines or one single image ; 
with a function call, you can also create a whole screen full of these objects ^ 
with that one call. This alone can greatly increase the effectiveness of graphic 
displays. 

Setting a Border 

Perhaps the most straightforward of these graphics objects is the border. The 
name is a historical accident; what you are really dealing with here is a 
generalized polygon drawing structure. A border can be: 

• A single line 

• An arbitrary collection of lines 

• A true polygon 
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Of course, a border can be used to render the rectangular area around a 
window or screen. These basic configurations are illustrated in Figure 5-1. 

Figure 5-1. Different kinds of borders 




An arbitrary collection 
of lines 



A single line 



A true polygon 



A border is defined by its corresponding structure. 



struct Border { 

SHORT Lef tEdge,TopEdge, 
FrontPen, BackPen, 
DrawMode, 
Count , 
*XY; 

struct Border *NextBorder; 

>; 
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Each border structure is associated with an array of integers (the actual 
data type is SHORT), that define the end points of the lines that will make up 
this particular object. 

LeftEdge and TopEdge define where the figure will appear within the 
enclosing structure. There is a natural tendency to see these two coordinates 
as the upper left-hand vertex of the proposed polygon. This may not be the 
case. LeftEdge and TopEdge actually define a reference point that sets the 
actual vertices of the figure: that is, those contained in the defining array. The 
point defined by these two values may, in fact, not even be a part of the drawn 
figure, and can even be enclosed by the figure it is used to measure. Figure 
5-2 delineates the important relationships between this point and the rest of 
the drawing. 

FrontPen is a pointer to a color register. It selects the color that will be 
used to draw the lines on the display. These colors must come from the 
current palette specified during the creation of the all-encompassing screen. 
This value will be further affected by the DrawMode field, which controls the 
way in which lines are painted on the display. Currently, the BackPen field is 
not used for drawing a border. 

DrawMode selects one of two possible ways of drawing the lines that will 
trace out a desired figure. A value of JAM1 causes the display to trace 
between the various vertices, using the color specified in the FrontPen field. 
These lines are laid over the background color without changing it. In con- 
trast, if this field is set with the COMPLEMENT flag, the border object will 
change the background to its binary complement along the figure lines. 
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Figure 5-2. The relationship of LeftEdge and TopEdge to the 
border figure 



•reference point in the containing element 



o (LeftEdge, TopEdge) 

first point of border 



The field XY is a pointer to the array that contains the points that define 
the figure. The Count field indicates how many sides the figure has. It is 
important to note that the Count field is not the number of vertices, but is 
actually the number of pairs of coordinate points in the drawing. A mistake 
here or a change in this field can cause the same set of data to draw very ! 
different figures. 

NextBorder is a pointer that allows a link to another border structure. 
Intuition enables such structures to form chains that will be given to the 
display, one after the other, by a single function call. This linked list of 
borders makes it possible to create efficient and complex displays. The last 
border structure in the chain must set this field to NULL. 

Once defined and initialized, the border structure can be used in 
a variety of contexts to create a figure for display. You can use it in con- 
junction with one of the other Intuition objects— menus or gadgets, for ■ 
example— to enhance the appearance and effectiveness of these construc- 
tioas. You can also send it directly to the window or screen; this is done via 
the DrawBorderi ) function. This border output function has the general, 
form: 

DrawBorder (RPort , Border , L_Off set , T_Of f set) 

RPort is a pointer to the Raster Port address associated with the win 
dow or screen in which our drawing is to take place. Border is a pointer to th 
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defined and initialized border structure. L_Offset and T ^Offset are values 
that will be added to the specified points in the vertex array. They allow a 
translation of the figure either up, down, or sideways in the display. These 
last two values can be zero. 

Listing 5-1. The creation of a simple border structure in 
a window. 

^include <exec/types.h> 

fine lude <i ntui t i on/ i ntu i t i on . h> 

struct Window *NoBorder; 
struct RastPort *r; 

SHORT points[]=<10,10, FO>- • 

400.10, 

SMS* 

10,10}; 



struct Border lines={0,0, 
5,0, 
JAM1 , 
5. 

NULL, 
NULL} ; 

mainO 

ULONG flags; 
SHORT x.y.w.h; 

VOID delay_funcO,0penALLO; 

OpenALLO ; /* Carried over from Chapter 3 */ 

/* ======0pen a borderless window======*/ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 

NoBorder=(struct Window *)make_window(x,y,w, h, NULL, flags) ; 
/* ======create a border structure========== */ 

lines. XY=points; 
r=NoBorder->RPort; 
DrawBorder(r,&lines,0,0) ; 

/* ======0e lay for a bit to show off the wi ndows====== */ 
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Listing 5-2. (cont.) 



/* ======open a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 

NoBorder=(struct Window *)make_window(x, y,w,h, NULL, f Lags) ; 

/* ======Create a border structure========== */ 

lines[0].LeftEdge=0; 
linesCO] .TopEdge=0; 
linesCO] . FrontPen=1 ; 
linesCO] .BackPen=0; 
linesCO] . DrawMode=J AM1 ; 
linesCO] .Count=5; 
linesCO]. XY=8pointsC0] CO]; 
LinesCO] .NextBorder=&linesC1 ] ; 

LinesCI ].LeftEdge=0; 
LinesCI ] .TopEdge=0; 
I i nesl"1 ] . FrontPen=2; 
Li nesC1 ] .BackPen=0; 
Li nesC1 ] . DrawMode=JAM1 ; 
L i nesC1 ] . Count=5; 
LinesCI]. XY=&poi nts C1 ] CO] ; 
LinesCI ] . NextBorder=& L i nes C2] ; 

LinesC2] .LeftEdge=0; 
LinesC2] .TopEdge=0; 
LinesL2] . Front Pen=3; 
LinesC2] .BackPen=0; 
LinesC2] . DrawMode=J AM1 ; 
LinesC2] .Count=5; 
LinesC2].XY=8pointsC2]C0]; 
LinesC2] .NextBorder=SLinesC3] ; 
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LinesC3] .LeftEdge=0; 
LinesC3] .TopEdge=0; 
LinesC3] .FrontPen=4; 
Lines C3].BackPen=0; 
Li nesC3] .DrawMode=JAM1 ; 
LinesC3] .Count=5; 
LinesC3].XY=SpointsC3]C0]; 
LinesC3] .NextBorder=NULL; 

r=NoBorder->RPort ; 

DrawBorder<r,8linesC0] ,10,10); 



/* ======De Lay for a bit to show off the wi ndows====== */ 
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Listing 5-2. (cont.) 



delay_func(100) ; 
/* =========c Lose down the windows in order========*/ 

delay_func(10); 



CLoseWindow(NoBorder) ; 

} 



VOID deLay_func(factor) 
int factor; 

/* This function will cause a specified deLay */ 
{ 

int Loop; 

for( Loop=0; Loop<f actor*1000; Loop++) 



return; 

> 



IntuiText 

Although Intuition offers specialized functions and support routines, along 
with data structures for putting text onto the display screen text, it is still 
just another type of graphics object. Remembering this will help you to keep 
straight the steps needed for this kind of display. Like the border, text has its 
own structure — IntuiText. It is necessary to create and initialize this struc- 
ture before you can render text. The IntuiText structure has the form: 

struct IntuiText { 

UBYTE FrontPen,BackPen, 

DrawMode 
SHORT LeftEdge.TopEdge; 
struct TextAttr MTextFont; 
UBYTE *IText; 

struct IntuiText *NextText; 

>; 

As with the border structure, there are associated data structures pecu- 
liar to the IntuiText structure, as well as some that are common to all of 
Intuition's graphics objects. 

ITextFont points to a structure that defines a particular type font. If you 
set this parameter to NULL, the text is rendered in the default style for that 
window or screen. Several fonts are available in the Font Library, and the 
Amiga allows the creation of new ones. IText is another pointer, this time to a 
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Figure 5-4. Output of Listing 5-2 




character string— an array of characters terminated by the character. This 
string contains the actual characters that make up cbis IntuiText structure. 

LeftEdge and TopEdge perform the same function here as they do with 
the border. These two values form a reference coordinate from which the text J 
position will be measured. 

FrontPen and BackPen each contain the value of a color register.; 
DrawMode sets the way in which text will be presented. The rendering of text 
on a display is somewhat more intricate than with the simpler border struc- 
ture. As a result, the relationship between DrawMode, FrontPen and 
BackPen is correspondingly more complex. The simplest case is set by choos- 
ing JAM 1 as the DrawMode. The text is rendered in the chosen font, in the 
color set by FrontPen, on the background of the display window or screen. A 
mode of JAM2 causes the characters to be displayed in the color indicated by 
FrontPen, but the background underneath will be changed by the BackPen 
reference. COMPLEMENT mode draws the characters, by tracing their out-| 
lines in the binary complement of the background color. 

Finally, NextText allows you to set up a string of IntuiText structures.V 
You can produce several lines of output with a single function call. 

The system call that translates your initialized structure to a display is| 

Print IText CRPort,IText,L_Offset,T_Offset) 
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Where RPort is a pointer to the enclosing objects RastPort, IText is a 
pointer to the IntuiText structure, and L_Offset and T_Offset are transla- 
tion values. These last two are added to the position values created by the 
structure itself. They allow you to reposition the text anywhere in the display 
without altering the structure. This translation capability is particularly 
handy if you are displaying the same text in a number of different objects 
within the display. You can have independent control of the text location in 
each object. You can also change text positions in one object without affect- 
ing the display elsewhere. 

A useful function unique to the IntuiText structure is: 

IntuiTextLength(IText) ; 

IText is a pointer to an IntuiText structure. This function returns the 
length of the display in pixels. This function is necessary whenever you need 
to know how much space a text display will require. Since text can be ren- 
dered in different fonts, the actual size of a given line of text can vary over a 
wide range. In any case, the pixel is a more appropriate unit of measure than 
the character. 

Listing 5-3 shows an example of a simple IntuiText structure in a win- 
dow. We create the structure, initialize it, and use it as a parameter in a call to 
PrintlTexti). We use the simplest situation and draw the text using the color 
pointed to by FrontPen. Note that we use an offset value of 0,0 in the function 
call. In this particular case, r is a pointer to the window's RastPort. Figure 
5-5 shows the resulting display. 

Listing 5-3. The creation of a simple IntuiText structure in 
a window. 



flinclude <exec/types.h> 

#i nc Lude <i ntui t i on/ i ntui t i on . h> 



struct Window *NoBorder; 
struct RastPort *r; 

struct IntuiText mesg; 

mainO 

ULONG flags; Z A $ 

SHORT x,y,w,h; 

VOID delay_func() .OpenALLO ; 
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OpenALLO; /* Add error checking */ 
/* ======0pen a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 

NoBorder=(struct Window *)make_window(x,y,w,h, NULL, flags) ; 
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Listing 5-3. (cont.) 



/» ======create an IntuiText structure========== */ 

nesg.FrontPen=5; 
nesg.BackPen=1 ; 
nesg.DrawMode=JAM1 ; 
nesg . Lef tEdge=10; 
nesg.TopEdge=10; 
nesg. ITextFont=NULL; 

nesg.IText=(UBYTE *)"This is only a Test!!!"; 

nesg.NextText=NULL; 

r=NoBorder->RPort; 

'rintIText(r,8mesg,0,0) ; 

/» ======Delay for a bit to show off the wi ndows====== */ 

delay_func(100); 

/* =========c Lose down the windows in order========*/ 

delay_func(10); 

C loseWi ndow (NoBorder) ; 

} 

VOID de Lay_func (factor) 
int factor; 

/*This function will cause a specified delay */ 
{ 

int loop; 

for(loop=0; loop<factor*1000; loop++) 
return; 



Listing 5-4 is a more ambitious program. Here we display several linked 
In;uiText structures. Again, we use the simple JAM1 DrawMode. The result; 
of this program is shown in Figure 5-6. 

Listing 5-4. Creation of linked IntuiText structures in 
a window. 



#include <exec/types.h> 

#inc lude <i ntuit ion/ intuit ion. h> 



158 



Chapter 5 



Figure 5-5. Output of Listing 5-3 




blue background 



Listing 5-4. (cont.) 



struct Window *NoBorder; 
struct RastPort *r; 

struct IntuiText mesg[3]; **A?ii4 4^ 

mainO 
{ 

ULONG flags; 
SHORT x,y,w,h; 

VOID delay_func(),0penALLO; 
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OpenALLO ; 

/* ======Open a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 

NoBorder=(struct Window *)make_wi ndow(x,y,w, h .NULL, f lags) ; 



159 



Drawing in Intuition 



Listing 5-4. (cont.) 



/* ======Create an Intuifext structure========== */ 

mesgCO] . FrontPen=5; 
mesgCO] .BackPen=1 ; 
mesgCO] . DrawMode=J AM1 ; 
mesgCO] . LeftEdge=0; 
mesgCO] .TopEdge=0; 
mesgCO] . IText Font=NULL; 

mesgCO], IText=(UBYTE *)"This is only a Test."; 
nesglO] .NextText=&mesgC1 ] ; 

mesgCI] .FrontPen=6; 
mesgCI] .BackPen=1 ; 
mesgCI] . DrawMode=J AM1 ; 
mesgCI] . Lef tEdge=30; 
mesgCI ] .TopEdge=10; 
mesgCI ] . IText Font =NULL; 
mesgCI ].IText=(UBYTE *)"Nothing can go wrong..."; 
mesgCI ] .NextText=&mesgC2]; 

mesgC2] . FrontPen=7; 
mesgC2] .BackPen=1 ; 
mesgC2] . DrawMode=J AM1 ; 
mesg[2] . Lef tEdge=60; 
mesgC2] .TopEdge=20; 
mesg[2].ITextFont=NULL; 

«nesg[2] . IText=(UBYTE *)"... go wrong.. '.go wrong..."; 
mesg[2] .NextText=NULL; 

r=NoBorder->RPort; 

Pr i nt IText (r.Smesg, 0,20) ; 



/* ======De Lay for a bit to show off the wi ndows====== */ 

delay_func(100); 

/* =========c lose down the windows in order========*/ 

delay_func(10) ; 



CloseWindow(NoBorder) ; 

> 



VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
{ 

int loop; 

for(loop=0; loop<f actor*1000; loop++) 
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Listing 5-4. (cont.) 



return; 

> 



Figure 5-6. Output of Listing 5-4 



white blacK orange blue background 




In this section, we have been concerned with creating and directly dis- 
playing text in a window or screen. But text can also be part of menus, 
gadgets, alerts, and requesters. The procedures are different in these more 
complicated cases, but they still utilize the IntuiText structure to define that 
part of the display. Some examples of these topics in Chapter 3 used this kind 
of structure without fully explaining it. We will turn our attention back to 
these objects and their relationship to text display later in this chapter. 

Images 

The most primitive of all Intuition graphics objects is the image. The image 
creates a display by specifying the color information contained in each pixel of 
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a proposed figure. Rather than creating a picture with a series of lines, you 
interact at the level of the display.itself, indicating which areas will be light and 
dark, and putting a specific color at a specific location. Intuition still shields 
you from the many details necessary to produce such a display. It gives you the 
capability of creating an image and displaying it anywhere on the display 
surface . . . even rendering the same image in more than one object. 

As with a border, an image is defined in two parts. The image structure 
carries the information needed to find a place for the object and to render it 
successfully. Contained in the image structure is a pointer to the actual pixel- 
by-pixel information that specifies the shape and the colors of the displayed 
image. This information is contained in an array, but the situation is more ;? 
complex than with the straightforward border array. 

The image-defining structure is deceptively short: 

struct Image { 

SHORT LeftEdge, TopEdge, 

Width, Height, Depth, 

♦ImageData; 
UBYTE PlanePick, PlaneOnOff; 
struct Image *NextImage; 

>; 

This structure maintains the same consistent design found in the two 
earlier structures: the positioning information and the pointer to the next 
graphic object. But there are some significant differences. 

Once you have created an object, LeftEdge and TopEdge allow you to move 
it around and position it anywhere within the visible display area. These two 
values represent a reference coordinate from which the painting of the image can 
be done. This is similar to the situation with border or even IntuiText objects. 
The width and height fields, in contrast, have a more active role to play in thej 
creation of an object. These two values indicate roughly the size of the obj 
they define a rectangular region within which your design is created. 

Nextlmage is a pointer to another image structure. With this, you 
maintain the Intuition tradition of specifying a chain of images that can bii 
controlled by a single function call. This adds to the efficiency and elegance of| 
graphics under Intuition. It also cancels out any overhead that might have 
been incurred by using this high-level interface to the system. ImageData iff 
another pointer; this one refers to an array that contains a series of 16-bit 
words. These words are logically manipulated into a rectangular display area 
bit map) which, in turn, is translated by the hardware into an image on th 
display screen. The height and width fields are used to make this translation. 
Each bit in each word is associated with a different pixel on the screen. By 
manipulating the value of the bit, you can alter the display of the correspon 
ing pixel. 

A single rectangular area allows you to produce a monochrome display. 
Either the pixel is on or off. The Depth field allows you to specify more thjgl 
one of these bit planes. With more bit planes, you open up the possibility <?f 
multiple colors in the display. The image structure allows extra flexibilij 
with the PlanePick and PlaneOnOff fields. By manipulating these fields, yo 
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can easily change the display characteristics of an image object. The 
PlanePick field allows you to match the bit planes of the image structure with 
the bit planes of the enclosing window or screen (Figure 5-7). PlaneOnOff lets 
Intuition know what to do with the bit planes that are not matched to the 
image. Depth specifies directly the number of bit planes used in the picture 
and thus, indirectly, the colors available to your pixels. 

Figure 5-7. The bit mask relationships for PlanePick 
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The final stage in the process is a call to the Intuition function: 
D raw Image ( RPort , ImagePtr.Xoffset.Yof fset) ; 

RPort points to the RastPort structure for the window or screen that 
displays the image. ImagePtr points to the current image structure. Xoffset 
and Yoffset provide displacement values for the object's position on the dis- 
play surface. 



Listing 5-5. Creation of a simple image structure in 
a window. 



^include <exec/types.h> 
^include <intuition/intuition.h> 

struct Window *NoBorder; 
struct RastPort *r; 

USHORT imagepts[]={Oxffff ,0x4f f e,0x3f f c,0x1ff8, 
OxOf f0,0x07e0,0x03c0,0x03c0, 
0x03c0,0x03c0,0x07f0,0x0ff0, 
0x1ff8,0x3ffc,0x4ffe,0xffff>; 

struct Image pi cture={0,0, 

16,16, 
3, 

NULL, 

0x0001,0x0000, 
NULL>; 

mainO 
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thing new with this definition; we specify LeftEdge and TopEdge as negative 
quantities. The enclosing object. in this case is the select box of the gadget. 
By using a negative offset, we can position our border figure outside of this 
select box, even though our reference is this figure. Border 0 and borderl are 
connected together into a linked list, but instead of a call to the DrawBorderf) 
function, we set the GadgetRender field to the address of border 0. When the 
gadget is summoned, the figure will be automatically drawn. The same tech- 
niques can be used with an integer or a boolean gadget. 

Figure 5-9. Output of Listing 5-7 



The Gadget Screen 
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In Listing 5-8, we have a more complex kind of gadget, the proportion- 
gadget. As you saw in Chapter 3, this simulates the kind of control four 
with an analog device in the real world— such as a control knob. Without' 
graphics interface, it is impossible to create an effective gadget of this 

Listing 5-8. A window with a proportional gadget. 



^include <exec/types . h> 
^include intuition/intuition. h> 

struct Screen *Scrn; 

struct Window *wind0,*wind1 ; 

struct Gadget gadget ; 

struct Proplnfo info; 

struct Image image; 

struct IntuiText message={1 ,0, 

JAM1 , 
-2,-9, 
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Listing 5-8. (cont.) 



NULL, 

"This is only a test!", 
NULL} ; 



#define INTUITION_REV 29 



' mai n () 
{ 

ULONG flags; 
SHORT x,y,w,h,d; 
USHORT mode; 
UBYTE *name,cO,d ; 
VOID delay_func() .OpenALLO; 

OpenALL O ; 

/* ======First create a gadget========= */ 

info.Flags=AUTOKNOB| FREEHORIZ| KNOBHIT; 
info.HorizPot=0; 
i nfo. VertPot=0; 
info.Hori zBody=0x0001 ; 
info.VertBody=0x0001; 

gadget .Next Gadget =NULL; 
gadget . LeftEdge=40; 
gadget .TopEdge=40; 
gadget .width=199; 
gadget .Height=10; 
gadget . F lags=GADGHCOMP; 
gadget. Ac ti vation=NULL; 
gadget. GadgetType=PROPGADGET; 
gadget .Gadget Render=(APTR)&i mage; 
gadget .Select Render=NULL; 
gadget .GadgetText=&message; 
gadget .Mutua LExc lude=NULL; 
gadget .Special Info=(APTR) Si nfo; 
gadget .Gadget I D=NULL; 
gadget .UserData=NULL; 

/* ======0pen a hi -res custom screen 

name="The Gadget Screen"; 

y=0; 

w=640; 

h=200; 

d=3; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 
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Listing 5-8. (cont.) 



make_screen(y,w,h,d,c0,c1 .mode, name) ; 
/* =======Open a wi ndow======= = = ===== */ 



FOi 



Ma 



name="Window 1"; 

<=20; 2 A H 

y=20; 

w=400; 

h=150; 

f lags=ACTIVATE|WINDOWSIZING|WINDOWDEPTH|WINDOWDRAG| 

UIN0OWCLOSE | SMART_REFRESH; 

c0=-0x01 ; 
d=-0x01; 

■ 

windO=(struct Window *) 

make_wi ndow(x,y,w,h, name, f lags, cO.d ,Scrn,&gadget) ; 

/* ======0eLay for a bit to show off the window====== */ 

delay_func(100) ; 

;* =========cLose down the window then the screen========*/ 

CloseWindow(windO) ; 
CLoseScreen(Scrn) ; 

> : i 

VOID delay_func(factor) 
i nt factor; 

/* This function will cause a specified delay */ 
{ 

int loop; 

1orUoop=0; loop<factor*1000; loop++) 
return; 



Recall that a proportional gadget requires a Special Info structure I 
addition to the gadget structure itself. This Info structure defines the value 
of the control interface portion of the gadget. Besides initializing the vahK 
of the control fields, in this structure you must also set certain key yalut 
that affect the display of the gadget. These values are set in the Flags field < 
this structure and include: 

FREEHORIZ or FREEVERT to indicate the direction of movement 

of the control device 
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Figure 5-10. Output of Listing 5-8 
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The Gadget Screen 




PROPBORDERLESS to display the gadget without a border around 
the container of the control device 

AUTOKNOB to indicate the default control device shape 

It is possible to create your own control object, but AUTOKNOB is a 
convenient default that produces an effective display. It shows the control 
surface as a rectangle within an outer rectangle that serves as a containing 
surface. In Listing 5-8, we have a control device that moves in the horizontal 
direction. There are two further things to note about the example in Listing 
5-8. Even though we are using the default AUTOKNOB object, we must 
declare an image structure and assign its address to the GadgetRender field 
of the gadget structure. This area is used by Intuition to build the 
AUTOKNOB object. This example also uses an IntuiText structure to place 
text into the gadget display. The gadget's GadgetText field is set to the 
address of this structure. This gadget is displayed in Figure 5-10. 

In Listing 5-9, we take our proportional gadget a step further. Here we 
define two complementary gadgets: one moves horizontally; the other, verti- 
cally. Notice that the two gadgets are also elegantly connected in a linked list. 
The result is visible in Figure 5-11. 

Listing 5-9. A window with two proportional gadgets. 

#include <exec/types . h> 
^include <intuition/intuition.h> 

struct Screen *Scrn; 
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Listing 5-9. (cont.) 



struct Window *wind0,*wind1 ; 
struct Gadget gadgetO, gadgetl ; 
struct Proplnfo infoO, infol ; 
struct Image imageO, i magel ; 
struct IntuiText message={1 ,0, 

JAH1 , 

-2.-9, 

NULL, 

"This is only a test!", 
NULL>; 

FORM., - 
' Z E B O 

ZARAGOZA 

OpenALLO ; 

/* ======Fi rst create a gadget========= */ 

i nf oO. F Lag s= AUTO KNOB | F REEHOR I Z | KNOBHIT; 
infoO.Hori zPot=0; 
infoO.VertPot=0; 
info0.HorizBody=0x0001 ; 
i nf oO . Ve rt Body=0x0001 ; 

gadgetO.NextGadget=(APTR)8gadget1 ; 

gadgetO. LeftEdge=40; 

gadgetO. TopEdge=40; 

gadgetO. Width=1 99; 

gadgetO. Height=10; 

gadgetO. Flags=GADGHCOMP; 

gadgetO.Acti vation=NULL; 

gadgetO.GadgetType=PROPGADGET; 

gadgetO. Gadget Render=(APTR) Si mageO; 

gadgetO.SelectRender=NULL; 

gadgetO. GadgetTex t=&message ; 

gadgetO. MutualExclude=NULL; 

gadgetO.SpeciaLInfo=(APTR)SinfoO; 

gadgetO. Gadget I D=NULL; 

gadgetO.UserData=NULL; 

infol .FLags=AUTOKNOB| FREEVERT| KNOBHIT; 

infol .HorizPot=0; 

infol .VertPot=0; 

i nf o1 . Hor i zBody=0x0001 ; 

infol .VertBody=0x0001 ; 

gadgetl .NextGadget=NULL; 
gadgetl . Lef tEdge=40; 



mainC) 
{ 

ULONG flags; 

SHORT x.y.w.h.d; 

USHORT mode; 

LIBYTE *name,cO,d; 

/OID delay_func() .OpenALLO ; 
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Listing 5-9. (cont.) 



gadgetl .TopEdge=55; 
gadgetl .Width=20; 
gadgetl .Height=75; 
gadgetl . F lags=GADGHCOMP; 
gadgetl .Acti vation=NULL; 
gadgetl . GadgetType=PROPGADGET; 
gadgetl .GadgetRender=(APTR)8image1 ; 
gadgetl . Se lectRender=NULL; 
gadgetl .GadgetText=NULL; 
gadgetl .MutualExc lude=NULL; 
gadgetl .SpecialInfo=(APTR)&info1 ; 
gadgetl .GadgetID=NULL; 
gadgetl .UserData=NULL; 
/* ======Open a hi-res custom screen==== */ 

name="The Gadget Screen"; 

y=0; 

w=640; 
h=200; 
d=3; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 , mode, name) ; 

/* =======open a wi ndow==============*/ 

name="Window 1"; 

x=20; 

y=20; 

w=400; 

h=150; 

f lags=ACTIVATE|WIND0WSIZING|UINDOWDEPTH|WIN0OWDRAG| 

WIN0OWCLOSE|SMART REFRESH; 

c0=-0x01 ; 
c1=-0x01; 

windO=(struct Window *) 

make_window(x,y ,w,h, name, flags, cO,d .Scrn.SgadgetO) ; 

/* ======De lay for a bit to show off the window====== */ 

delay_func(100); 
/* =========ciose down the window then the screen========*/ 

CloseWindow(windO); 

CloseScreen(Scrn) ; 
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Listing 5-9. (cont.) 



VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
{ 

int Loop; 

for(loop=0; Loop<f actor*1000; Loop++) 



return; 



} 



Figure 5-11. Output of Listing 5-9 




The Gadget Screen 




A Practical Gadget Library 

Gadgets are such an integral part of the Intuition operating environment 
it would certainly be useful to call up such an object whenever the need . 
Just as the C programmer can call upon getchar( ) or scanf( ) to grab, J 
from stdin without any special attention to the details of these function 
Intuition programmer could use comparable gadget functions that 
requested values. Figure 5-12 illustrates three such gadgets: one forf 
tional input, one for string input, and one with an integer gadget. 
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Figure 5-12 A package of three gadgets 
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Some attention should be paid to the graphic design of these library 
gadgets. Note first that they are all similar in labelling and layout. Note 
further that each gadget is a window containing a composite gadget. Two 
Boolean ones, titled OK! and Cancel, actually control the operation of the 
composite object. Values are placed in the main gadget, whether string or 
proportional or integer, but nothing is returned until one of the Boolean ones 
is clicked. They perform a function similar to the carriage return with the 
getchii) or scanf( ) functions in C. 

Listing 5-10 contains the code for the library functions. First, the data 
structures defining the gadgets must be declared and defined. Each of the 
five gadgets has its own definition although some of the data structures 
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Listing 5-10. (cont.) 



struct Window *window; 
int rvalue; 
sgadg.Buffer=buffer; 

NewWindow. Screen=Cscrn == NULL) ? WBENCHSCREEN : scrn; 



ogadget .NextGadget=8cgadget ; 
sgadget . Next Gadget=8ogadget ; 



/* create the chain of gadgets * 



NewWindow.FirstGadget=8sgadget; /* put the chain in the window 

window=(struct Window *)OpenWindow(8NewWindow) ; 

rvalue=get_f lag(window); 



CloseWindow(window) ; 
return rvalue; 



get _int( value, scrn) 
LONG 'value; 
struct Screen *scrn; 
C 

struct Window *window; 



55 B B O 

Z ARAGOZ A 



static char buf f er[80]="0"; 
int rvalue; 
igadg.Buffer=buffer; 

NewUindow.Screen=(scrn == NULL) ? WBENCHSCREEN : scrn; 



ogadget. NextGadget=8cgadget; 
i gadget . NextGadget=8ogadget ; 



/* create a chain of 3 gadgets */ 



NewWindow. FirstGadget=8igadget; /* initialize the NewWindow structur 
window=(struct Window *)OpenWindow(8NewWindow) ; 



rvalue=get_f lag(window) ; 
*va lue= i gadg . Long I nt ; 

CloseWindow(window); 
return rvalue; 



/* get the OK! /Cancel message */ 
/* return the parameter value */ 



/* get flagO will handle i/o from the OK! and Cancel gadgets whic 
common to the functions. */ 



get_f lag(window) 



ISO 



Chapter 5 



Listing 5-10. (cont.) 



struct Window *window; 
< 

struct IntuiMessage *msg,*GetMsgO ; 
int flag=-1; 
for(;;) { 

Waitd « window->UserPort->mp_SigBit); 
whi Le((msg=GetMsg(window->UserPort))) { 

if (msg->Class == GADGETUP) /* capture a gadget message */ 

if (msg->IAddress == (APTR)Sogadget) { /* Ok! gadget selected. */ 
ReplyMsg(msg) ; 
flag=1; 
break; 

} 

else if (msg->IAddress == (APTR)Scgadget) { /* Cancel gadget 

picked */ 

f lag=0; 

ReplyMsg(msg) ; 
break; 

> 

> 

if (flag != -1) /* if no pick, continue until there is one */ 

break; 

> 

return flag; 

> 



The function get_prop() creates a proportional gadget and returns its 
values through the pointer wiriables hval and wal. The function itself returns 
the flag value generated by the pair of Boolean gadgets generated by a call to 
get_flag(). Note that the function first sets up a linked list of structures, 
places this in a NewWindow structure and opens a window. This window 
structure is closed just prior to the end of the function. The scrn parameter is 
a pointer to an enclosing screen or NULL to indicate the standard workbench 
screen. It should be noted that whichever Boolean gadget is chosen, the 
current value of the proportional gadget is returned. 

Get^stringO will also create a three way gadget setup within a window. 
In this case, however, a string gadget has the central honor. This string value 
is returned through the character pointer buffer. As before, the function 
returns a value that was extracted from a call to get_value and, at that point, 
returns the current value in buffer. Get_int() works in an analogous fashion, 
but here the long integer value is found in the Longlnt field of the gadget 
structure and returned through the parameter value. 

Once we have compiled this file to object form, whenever we wish to use 
these functions, we merely link this object file along with our main program 
file and all the other support files. The advantage of these functions is that 
they are ready to use just like the functions found in the standard library. 
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Listing 5-11 illustrates a simple program that can be used to test this gadget 
library. 

Listing 5-11. A driver program to illustrate the gadget library. 



^include <exec/types . h> 
#include <i ntui t i on/ intuit ion. h> 
#include <lattice/stdio.h> 

mainO 
{ 

USHORT h,v; 
LONG x; 

char cmd,bufferC80] ; 



FORMAT 
ZERO 

ZARAGOZ A 



OpenAUO; 

if (!get_prop(&h,8v,NULD) 
exitO ; 

printf ("nor i zont a l=%u verti cal=%u\n",h, v) ; 
cnd=getchar () ; 

if (!get_string (buffer, NULL)) 
exitO ; 

printf ("buff er=%s\n", buffer) ; 
:md=getchar() ; t 

if C!get_int(&x,NULL>) 
exitC): 

pn'ntfC'long value=%ld\n",x) ; 

} 



ROM Kernel Graphics Commands 

Beneath Intuition, underlying and supporting it, is the executive kernel. Tl 
contains the most basic system calls and the essential multitasking suppo 
routines. This collection of software is often called the ROM kernel or th ; 
Exec kernel. Among the system services provided by this low-level kernel is 
complete set of graphics and display routines. These are functions that 
rectly interact with the specialized graphics chips that are a unique feature 
the Amiga: the blitter and the copper. These routines work independently 
Intuition— indeed they support it— but they can also be used within Intui' 
to create more efficient graphics displays. 

The connecting link between Intuition and these routines is a b 
structure of the graphics kernel, the RastPort. This is a specialized mess 
port that allows communication with individual display areas. The RastP^ 
is a fairly complex structure and a more basic one than a screen or a windo 
although in operation it is similar. Fortunately, Intuition opens and initia 
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a RastPort for each screen and window that it opens. Access to these is found 
in the respective Intuition structures: 

• For screens this is the RastPort field. 

• For windows, it is RPort. 

This greatly simplifies life for the programmer. It allows the creation of 
elaborate graphics displays without having to manage all the details of the 
display. What is more important, these graphics displays exist under the well- 
behaved rules of the Intuition interface. This is also a situation where a 
. GIMMEZEROZERO or a backdrop window can be used to good effect. 

Setting Up the RastPort 

Each window or screen has its own RastPort structure. Within this structure 
are a number of fields which relate to the action of specific graphics kernel 
functions. It is sometimes necessary to set these fields and then pass the 
RastPort structure as a parameter to a particular function. These fields refer 
to certain actions within the graphics hardware, or set default values. 

The first such set of values contains the drawing pens defined in the 
RastPort structure. These pens are pointers to one of the thirty-two color 
registers maintained by the Amiga to control the display. There are three pens: 

• FgPen sets the primary drawing color^ 

• BgPen is the background color. 

• AOlPen is the color used for area outlining. 

Each one of these is set by a specific system function: SetAPenf), 
SetBPenO, and SetOPenf) respectively. The format of each of these is identi- 
cal. For example, to set the FgPen, call: 

Set APen (RPort, Co lor); 

Here RPort is a pointer to a RastPort structure, and Color is a value 
which indicates a color register. The range over which Color can vary is 
dependent on the depth of the structure attached to RPort. 

The format of a graphics display is set by the drawing mode. As with the 
Intuition-specific functions, this specifies the interplay between foreground 
and background colors. Four are possible: 

• JAM1 replaces each pixel indicated by the color of the FgPen. 

• JAM2 is more complicated, utilizing both FgPen and BgPen to 
produce a pattern. 

• COMPLEMENT sets the pixels to their complement value. 

• INVERSEVID draws text in a way that inverts its normal appearance. 
These modes are set by a call to SetDrMdf). This has the general form: 
SetDrMd(RPort.Mode); 
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Again, RPort is a pointer to a RastPort structure. Mode is one of the 
legal modes mentioned above— except in the case of INVERSVID, which can 
be combined with either JAM1 or JAM2 to produce different effects. 



Drawing Support 

Several graphics kernel functions are available to facilitate line drawing on 
the display. 

Move(RPort,x,y) 

repositions the drawing cursor from its current position to coordinates 
defined by x and y. RPort points to the RastPort of the object in which this 
movement is to take place. This is a positioning function; no output is shown. 
To draw a line between two points, use: 

Draw(RPort,x,y) ; 

Note that this has precisely the same form as the Move() function, but in 
this case a line is drawn connecting the current position with the new one. The 
cursor is also moved to the new point. 

Draw() sketches its line in the color set by FgPen. To produce a series of 
multicolored lines, it is only necessary to combine this function with 
SeiAPenO. Listing 5-12 illustrates a program that uses this combination to 
create bars of color in a window. The function makebaii) draws a series of 
lines in a single color across the display. The number of vertical lines drawn is 
set by the parameter lin. The color of the line is also a parameter. The main 
program loops through sixteen colors, calling makebari) for each iteration. 

lasting 5-12. The use of ROM kernel graphics routines in a 
window (running in Intuition). 

^include <exec/types.h> 
# include <intuition/intuition.h> 

struct Window *NoBorder; 
struct RastPort *r; 
struct Screen *Scrn; 

mainO 
{ 

ULONG flags; 
SHORT x,y,w,h,d,c0,c1 ; 
USHORT mode; 

VOID delay f unc () , OpenALL O ; 
int i,j; 



OpenALL O ; 

/* ======Open a hi-res custom screen 1 



=== */ 
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Listing 5-12. (cont.) 



y=0; 
w=640; 
h=400; 
d=4; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h f d,c0,c1 , mode, NULL) ; 

/* ======Open a borderless window======*/ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 
NoBorder=(struct Window *) 

make_window(x,y,w,h,NULL,f lags.Scrn) ; 

/* ======Draw some lines========= */ 



r=NoBorder->RPort; 
j=0; 

for(i=0;i<=16;i++) { 
make_bar (i , 10, r, j ) ; 
j+=10; 

} 



/* ======oelay for a bit to show off the wi ndows====== */ 

delay_func(100) ; 
/* =========C lose down the windows in order========*/ 

delay_func(10); 



CloseWindow(NoBorder) ; 
CloseScreen(Scrn); 

} 

make_bar(col , lin,rast,y) 

int col, lin; 

struct RastPort *rast; 

SHORT y; 

{ 

int j; 

SetAPen(rast,col) ; 
for(j=0; j<lin; j++) { 
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Listing 5-12. (cont.) 



Move(rast,10,y+j); 
Draw(rast,600,y+j); 

} 

) 



To draw a series of connected lines (a polygon), use: 

PolyDrawCRPort, count, array); 

This functions much as the DrawBorderf ) function found in Intuition. 
The coordinate for each vertex is placed in an array. This array is passed to 
the function, along with a count of the number of sides and a pointer to tha 
EastPort structure of the enclosing device. This function uses FgPen to 
render the lines. 

Listing 5-13. The PolyDraw( ) function, using ROM kernel 
graphics routines in a window (running in Intuition). 



flinclude <exec/types . h> 
Si nc Lude <i ntui t i on/i ntui t i on. h> 



2E .B O 

ZARAGOZ h 



struct Window *NoBorder; 
struct GfxBase *GfxBase; 
struct Screen *Scrn; 

ma i n ( ) 
{ 

ULONG flags; 
SHORT x,y,w,h,d,cO,d; 
static SHORT poly[]={450,10, 
600,75, 
450,150, 
150,150, 

10.75, 
150,10}; 

USHORT mode; 

VOID delay_func(),0penALLO; 
OpenALLO ; 

/* ======open a hi-res custom screen==== */ 



y=0; 
w=640; 
h=400; 
d=4; 

c0=0x00; 
c1=0x01 ; 
mode=HIRES; 
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Listing 5-13. (cont.) 



Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 , mode, NULL) ; 

/* ======0pen a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

. f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 
NoBorder=(struct Window *) 

make_window(x,y,w, h, NULL, flags, Scrn) ; 

/* ======Draw some lines========= */ 

r=NoBorder->RPort; 

SetAPen(r,5) ; 
Move(r,150,10); 
PolyDraw(r,6,poly) ; 

/* ======De lay for a bit to show off the wi ndows====== */ 

delay_func(100); 
/* =========ciose down the windows in order========*/ 

delay_func(10) ; 



CloseWindow(NoBorder) ; 
C LoseScreen(Scrn) ; 

> 

VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
< 

int loop; 

for(loop=0; loop<factor*1000; loop++) 



return; 



In Listing 5-13 we use PolyDrawO to produce a figure in a window. The 
array poly contains the coordinate points for each vertex in our figure. We 
position the cursor at position 150,10 through a Moved function. PolyDrawO 
takes our initialized RastPort structure, the array of vertices, and the count 
of the sides of our figure, and draws it. 

Figure 5-13 shows the result. 



187 



Drawing in Intuition 



Figure 5-13. Output of Listing 5-13 




pink 



blue background 



With these three functions— Move(), Draw(), and PolyDrawf )— it is necsj 
essary that the application do its own boundary checking. In each of these! 
functions, if a point is specified that lies outside the bit map supplied by thej 
RastPort structure, the results will be unpredictable. 

In addition to the above functions, there are a pair of function calls 
give you a handle on individual pixels: 

ReadPixel(RPort,x,y); 

This function returns an integer value— the value of the color found at 
position— ranging from 0 to 255. If you specify a point outside the area defin 
as the display, a value of —1 is returned. The complementary function is: 

WritePixel(RPort,x,y) 

This puts a pixel at the specified x,y coordinate. FgPen supplies 
color. A value of —1 returned by this function indicates an out-of-boundjj 
condition for the coordinates. If the function call is successful, 0 is return 



Area Fill 

One of the most important of all graphics operations is filling an arbit 
polygon on the display with either a color or a pattern. The Amiga has 
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capability built into its hardware— a feature which it shares with very expen- 
sive graphics work stations. This means that fill operations are done signifi- 
cantly faster than with systems where the work must be done in software. 
Access to this specialized hardware is through several system calls. Each of 
these calls allows you to do the fill operation in a slightly different way. The 
simplest fill operation allocates and fills a rectangle in the display with a 
specified color. The necessary function call for this operation is: 

RectFi ll(Rport,xmin f ynn'n,xmax,ymax) ; 

RPort is a pointer to the RastPort of the enclosing figure. Xmin, ymin, 
xmax, and ymax define a rectangle by specifying its upper left-hand and 
lower right-hand coordinates. The color used for the fill operation is depend- 
ent on the drawing mode and the three pens defined in the RastPort struc- 
ture. In its simplest mode— JAM1— the color is a solid and only FgPen is used 
to render the display. 

Listing 5-14 illustrates this simple case. Here we set the FgPen color 
through the SetAPenO function. A call to RectFillO produces a filled square 
with its upper left-hand corner at coordinate 10,10. 

Listing 5-14. The RectFilK ) function, using ROM kernel 
graphics routines in a window (running in Intuition). 



#include <exec/types . h> 
#inc Lude <intuition/intuition.h> 
#include <graphi cs/gf xraacros.h> 

struct Window *NoBorder; 
struct RastPort *r; 
struct Screen *Scrn; 

ma i n ( ) 
{ 

ULONG flags; 
SHORT x,y,w,h f d,cO,d ; 
USHORT mode; 

VOID delay_func() .OpenALLO ; 
OpenALLO ; 

/* ======0pen a hi-res custom screen==== */ 

y=0; 

w=640; 
h=400; 
d=4; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 .mode, NULL) ; 



z E H o 
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Listing 5-14. (cont.j 



/* ======Open a borderless wi ndow======*/ 

x=y=0 
w=640 
h=200 

f Lags=ACTIVATE| SMART_RE FRESH | BORDERLESS; 
NoBorder=(struct Window *) 

make_wi ndow(x,y,w,h, NULL, f Lags, Scrn) ; 



*/ 



= */ 



/* ======0raw some Lines====== 

r=NoBorder->RPort ; 

SetAPen(r,2) ; 
SetOPen(r,3) ; 

RectFi LL(r,10,10,100,100); 

/* ======0e Lay for a bit to show off the wi ndows===== : 

deLay_func(100); 

/* =========C Lose down the windows in order========*/ 

deLay_func (10) ; 

CLoseWindow(NoBorder) ; 
CloseScreen(Scrn) ; 

> 

VOID deLay_func(factor) 
int factor; 

/* This function wilL cause a specified deLay */ 
{ 

int Loop; 

for(Loop=0; Loop<f actor*1000; Loop++) 
return; 



A true polygon fill can be accomplished by using the AreaMoveO any 
AreaDrawO functions, but these, in turn, are dependent on two struci 
associated with the RastPort of the enclosing object— either screen or 
do-w. The first of these is Arealnfo. This structure sets up a buffer to sfc 
information about the figure that is being created by the fill functions^, " 
initialized by a call to: 



190 




Chapter 5 



Init Area (A Info, buffer, count) ; 

AInfo points to an Arealnfo structure; buffer is a pointer to a storage 
area for the figure being drawn, and count indicates the size of the figure in 
question. Buffer holds, temporarily, the coordinates of the vertices that define 
the polygon. As a rule of thumb, you need to set aside about five bytes of 
storage space per vertex. AInfo is assigned to the Arealnfo field of the 
RastPort structure. 

Once you have a storage space for the parameters of your figure, you 
must allocate a workspace for the drawing routines themselves. This is ac- 
• complished by declaring a TmpRas structure. This is usually set to the full 
size of the screen— 200 by 320 in low-resolution and 200 by 640 in high- 
resolution mode. This space is set aside by a call to: 

Init TmpRas (TRas.buf f er,size) ; 

Here TRas is a pointer to a TmpRas structure, buffer points to a block of 
memory; and size is an integer indicating the size of the buffer area. The 
TmpRas field of the RastPort structure is set to the address returned by this 
function. 

With the initialization of these two workspaces, it is possible to define 
an arbitrary area to be filled. The first function to be called is: 

AreaMove(RPort,x,y) ; 

This function performs a dual service. It closes any pending polygon by 
connecting its last drawn coordinate to its initial point. The position x,y is 
recorded in the previously defined buffer and a new figure is started. A call to: 

AreaDrawCRPort ,x,y) 

stores new x,y coordinates in this buffer. Note that nothing has been 
rendered on the display at this point. A final call to: 

AreaEnd(RPort) 

terminates the figure and also causes it to appear on the display monitor. 

Listing 5-15. Area fill, using ROM kernel graphics routines in a 
window (running in Intuition). 



#incLude <exec/types.h> 
#incLude <intuition/intuition.h> 
#incLude <graphi cs/gf xmacros.h> 

2ER0 
2ar agoz a 
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struct Window *NoBorder; 

struct RastPort *r; 

struct Screen *Scrn; 

struct TmpRas TRas; 

struct Arealnfo AInfo; 
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Listing 5-15. (cont.) 



mai n() 
{ 

ULONG flags; 

SHORT x,y,w,h,d,c0,c1 ; 

static SHORT Buf f erl500] ; 

LISHORT mode; 

VOID delay_funcO, OpenALLO; 
OpenALLO; 

f* ======Open a hi -res custom screen==== */ 

y=0; 
w=640; 
h=400; 
d=4; 

c0=0x00; 
c 1=0x01 ; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w, h,d,c0,d , mode, NULL) ; 

/* ======Open a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 
NoBorder=(struct Window *) 

make_window(x,y,w,h,NULL,f lags.Scrn) ; 

f* ======Draw some lines========= */ 

r=NoBorder->RPort ; 

InitArea(&AInfo, Buffer, 200); 

r->AreaInfo=8AInfo; 
r->TmpRas=(struct TmpRas *) 

InitTmpRas(8TRas,AllocRaster(320,200),RASSIZE(320,200) 

AreaMove(r,0,0) ; 
AreaDraw(r,75,0) ; 
AreaDraw(r,75,75) ; 
AreaDraw(r,0,75) ; 
AreaEnd(r) ; 

f* ======Delay for a bit to show off the wi ndows====== *JA 

delay_func(100) ; 
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Listing 5-15. (cont.) 



/* =========c lose down the windows in order========*/ 

delay_func(10) ; 



CloseWindow(NoBorder) ; 
C loseScreen(Scrn) ; 

-> 

VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
{ 

int loop; 

for( loop=0; loop<f actor*1000; loop++) 



return; 

> 



Listing 5-15 shows the production of a simple figure. We use the 
RastPort pointer supplied by the open window, and we set aside 200 bytes to 
draw a four-sided figure— more than enough. A series of AreaDrawi ) function 
calls, bracketed by an AreaMovet ) and an AreaEndf), completes the picture. 

Listing 5-16. Area fill with outlining, using ROM kernel 
graphics routines in a window (running in Intuition). 



^include <exec/types.h> 

#i nc lude <i ntui t i on/ i ntui t i on . h> 

^include <graphics/gfxmacros.h> 

struct Window *NoBorder; 
struct RastPort *r; 
struct Screen *Scrn; 
struct TmpRas TRas; 
struct Arealnfo AInfo; 

ma i n ( ) 
{ 

ULONG flags; 
SHORT x.y.w, h.d.cO, ec- 
static SHORT Buffer[500]; 

USH0RT mode; 

VOID delay_func(), OpenALLO ; 
OpenALLO; 



FORMA? 
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Listing 5-16. (cont.) 



/* ======o P en a hi -res custom screen==== */ 

«2io; FORMA? 
SU ZERO 

ZAR&GOZA 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 , mode, NULL) ; 

/* ======Open a borderless wi ndow======*/ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART REFRESH | BORDERLESS; 
NoBorder=(struct Window *) 

make_wi ndow <x, y.w.h, NULL, f Lags, Scrn); 

/* ======oraw some li nes========= */ 

r=NoBorder->RPort; 

InitArea(8AInfo, Buffer, 200); 

r->AreaInfo=8AInfo; 
r->TmpRas=(struct TmpRas *) 

InitTmpRas(8TRas,AUocRaster(320,200),RASSIZE(320,200)); i 
SetOPen(r,3); 

AreaMove(r,0,0); 
AreaDraw(r,75,0) ; 
AreaDraw(r,75,75) ; 
AreaDraw(r,0,75) ; 
AreaEnd(r) ; 



/* ======oelay for a bit to show off the wi ndows====== */ 

delay_func(100) ; 
/* =========CLose down the windows in order========*/ 

deLay_func(10); 



CloseWindow(NoBorder) ; 
CloseScreen(Scrn) ; 
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VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
int loop; 

• for(loop=0; loop<f actor*1000; loop++) 



return; 

> 



Listing 5-16 shows an interesting variation. By setting the AOlPen to a 
contrasting color, we produce a filled figure that is also outlined. Figures 5-14 
and 5-15 show the results of these two examples. 

Figure 5-14. Output of Listing 5-15 




no border white blue background 



The area fill routines that we have used so far both create and fill a 
figure with color. It is sometimes necessary to draw a figure so that it 
appears on the screen or window in outline form, and then fill it. This is 
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Listing 5-17. (cont.) 

/* ======n e lay for a bit to show off the wi ndows====== */ 

delay_func(100); 

h =========ciose down the windows in order========*/ 

ielay_func<10); FORM^^ 
Closewindow(NoBorder); , 2j £2 O 

CloseScreen(Scrn) ; ZARA©01^ 

VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
int loop; 

for( loop=0; loop<f actor*1000; loop++) 
return; 

} 



Fining with a Pattern 

The RastPort structure contains two fields that support the use of patterns 1 
with graphics objects. 

1 You can specify a line drawing pattern that will allow you to create i 
various forms of dotted or dashed lines. I 

2 You can specify an area fill pattern and use it in place of a solid color 
during a fill operation. 

These capabilities are controlled by two macros: SetDrPt() and 
SetAfPtf). These macros are found in the header file graphics/ 'gfxmacros.h. 
This file must be explicitly included before the definition of any function or 
program that is to do pattern fill. 

The simplest form of pattern drawing is that of a line. The line pattern is 
a 16-bit quantity, applied to all lines controlled by the RastPort. The pattern 
can be set or reset at any time via the macro command: 

SetDrPt (RPort .pattern) ; 

Pattern is a number, usually specified in hexadecimal, which indicates 
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no border orange blue background 

the form of the line pattern. For example, Oxffff represents the bit pattern, 
1111111111111111. This is a solid line, the default condition when the RastPort 
is initially opened. A value of 1 in a bit position forces the line drawing 
routines to put in a solid section; a 0, a blank space. The bit pattern 
0101111101011111, indicates a more complex pattern; it would be specified by 
the number 0x5f5f. Area pattern fill requires a more complex operation. An 
area pattern is a rectangle sixteen bits wide, but it can be any height as long 
as the height is a power of two. Thus, you can create a pattern that is 1, 2, 4, 
8, or any higher power of two. This pattern can then be used to fill a figure in 
place of the solid color used above. 

An area fill pattern is defined in an array. Each member of the array 
represents one line of the pattern. A 1 bit indicates that a pixel will be drawn. 
A 0 bit defines that space as an empty area. Once you have defined this 
pattern, you can call the macro: 

Set AfPt (RPort, Pat Array, Size); 

PatArray is a pointer to the array just defined containing the pattern, 
and Size indicates indirectly how many lines you have defined within the 
pattern. This value is the power of two that indicates this quantity. Once you 
have executed this setup procedure, whenever you specify a fill operation, this 
pattern will be used. 
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Listing 5-18. The RectFilH ) function with a pattern, using 
ROM kernel graphics routines in a window 
(running in Intuition). 



^include <exec/types.h> 

flinc Lude <i ntui t i on/ intuit ion. h> 

^include <graphi cs/gf xmacros.h> 



ZEBO 

ZARAGOZA 



struct Window *NoBorder; 
struct RastPort *r; 
struct Screen *Scrn; 

USHORT pat[]={ OxffOO, 
OxffOO. 
OxOOff , 
OxOOff , 
OxfOfO, 
OxfOfO. 
OxOfOf , 
0x0f0f>; 

mai nO 
£ 

ULONG flags; 

SHORT x,y,w,h,d,c0,c1; 

USHORT mode; 

VOID delay f unc () .OpenALLO ; 



OpenALLO; 

/* ======Open a hi-res custom screen==== */ . 

y=0; 
w=640; 
h=400; 
d=4; 

cOOxOO; 
c1=0x01 ; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 , mode, NULL) ; 

/* ======Open a borderless window======*/ 

x=y=0; 
w=640; 
h=200; 

flags=ACTIVATE|SMART_REFRESH| BORDERLESS; 

NoBorder=(struct Window *) 

make_wi ndow(x,y,w,h, NULL, f lags. Scrn); 



/* ======Draw some lines==== 

r=NoBorder->RPort; 



*/ 



iS 
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Listing 5-18. (cont.) 



SetAPen(r,2) ; 
SetOPen(r,3) ; 
SetBPen(r,4) ; 

SetAfPt(r,pat,3) ; 
SetDrMd(r,JAM2); 

' RectFill(r,10,10,100,100); 

/* ======Delay for a bit to show off the wi ndows====== */ 

delay_func(100); 
/* =========C Lose down the windows in order========*/ 

delay_func (10) ; 



CloseUindow(NoBorder) ; 
CloseScreen(Scrn) ; 

> 

VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
int loop; 

for(loop=0; loop<f actor*1000; loop++) 



return; 



Pattern fill is shown in Listing 5-18 and Figure 5-17. Here we set up a 
pattern using the SetAfPtf) macro and do a rectangle fill. Note that we set 
the drawing mode to JAM2; this will render the pattern using the FgPen to 
color the 1 bits and the BgPen to draw the 0 bit positions. 

|e Miscellaneous Functions 

will close out this chapter by turning attention to two functions that 
*re simple to use, yet offer a high level of convenience to the graphics 
programmer. 

||| v S«tRast(RPort,Pen) 
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Figure 5-17. Output of Listing 5-18 




sets the entire raster display to the color of the pen specified by the Pen 
parameter. Listing 5-19 illustrates the use of this function. We set FgPen to 
point to a specific color register and pass it to the function, along with a 
pointer to the RastPort structure. The result, shown in Figure 5-18, is 
change to that color for the entire display. This function can be used to make 
such a global change quickly. 

Listing 5-19. SetRast( ) function, using ROM kernel graphics 
routines in a window (running in Intuition). 



finclude <exec/types.h> 
#include <i ntui t i on/ intuit ion. h> 
^include <graphics/gfxmacros.h> 

struct Window *NoBorder; 
struct RastPort *r; 
struct Screen *Scrn; 

mainO 
{ 

ULONG flags; 

SHORT x,y,w,h,d,c0,c1 ; 
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Listing 5-19. (cont.) 



USHORT mode; 

VOID delay_func(),0penALLO; 
OpenALLO ; 

/* ======Open a hi-res custom screen==== */ 



y=0; 



w=640; ^Offcj 



cO=0xOO; ^ J$ J| 

mode=HIRES; ^ ^ ^ ^ G < 



d=0x01; Za 

Z A 

Scrn=(struct Screen *) 

raake_screen(y ,w,h,d,cO, c1 .mode, NULL) ; 

/* ======Open a borderless window======*/ 

x=y=0; 
w=640; 
h=200; 

f I ags= ACTIVATE | SMART_RE FRESH | BORDERLESS; 
NoBorder=(struct Window *) 

make_wi ndow ( x, y,w,h, NULL, f lags, Scrn) ; 

/* ======Draw some lines========= */ 

r=NoBorder->RPort; 

SetAPen(r,3); 
SetRast (r,r->FgPen) ; 

/* ======0e lay for a bit to show off the wi ndows====== */ 

delay_func(100) ; 
/* =========C lose down the windows in order========*/ 

delay_func (10) ; 

CloseWindow(NoBorder) ; 
CloseScreen(Scrn) ; 



VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
{ 

int loop; 
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Listing 5-19. (cont.) 



1or( Loop=0; Loop<f actor*1000; loop++) 
return; 

} 



Listing 5-21 illustrates another simple yet powerful function: 

ScrollRaster(RPort,delta_x,delta_y,xmin,ymin f xmax.ymax) 

This causes a section of the display attached to the specified RastPort 
structure to scroll in either a horizontal direction, a vertical direction, or both. 
The area over which this scrolling takes place is defined by the variables 
xmin,ymin,xmax,ymax. Delta_x and delta_y indicate the incremental 
change in the position of the display. Areas vacated by the objects in the 
display are replaced by the background color. Figure 5-19 shows the output 
frcm this example. 

Figure 5-18. Output of Listing 5-19 




orange 
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Listing 5-20. The ScrollRaster( ) function, using ROM kernel 
graphics routines i n a window (running in Intuition). 

#include <exec/types.h> 

U i nc I ude <i nt u i t i on / i nt u i t i on . h> 

struct Window *NoBorder; 
struct RastPort *r; 

USHORT imagepts[]=-COxffff ,0x4ffe,0x3ffc,0x1ff8, 
0x0ff0,0x07e0,0x03c0,0x03c0, 
0x03c0,0x03c0,0x07f0,0x0ff0, 
0x1ff8,0x3ffc,0x4ffe,0xffff}; 

struct Image pi cture={0,0, 

16,16, 
3, 

NULL, 

0x0001,0x0000, 
NULL>; 



mai n () 
{ 

ULONG flags; 
SHORT x,y,w,h; 

VOID delay_func() ,0penALLO ; 
i nt i ; 



Z E R q 
Za *agoza 



OpenALLO ; 

/* ======0pen a borderless window===== */ 

x=y=0; 
w=640; 
h=200; 

f lags=ACTIVATE | SMART_REFRESH | BORDERLESS; 

NoBorder=(struct Window *)make_window(x ,y ,w, h.NULL, f lags) ; 

/* ======Create an image structure============== */ 

pi cture. ImageData=imagepts; 

r=NoBorder->RPort ; 

Drawlmage(r,8picture,50,50) ; 

delay_func(10); 

for(i=0;i<50;i++) 
ScrollRaster(r,0,1, 10,10, 100, 100); 

/* ========Delay for a bit to show off the windows======== */ 

delay_func(100) ; 
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Listing 5-20. (cont.) 



/* ======-=C lose down the windows in order=========*/ 

PORMAV 

CLoseWindow(NoBorder); i ] I J | Q 

ZARAGOZ A 

VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
int loop; 

for(loop=0; loop<f actor*1000; loop++) 
return; 



Figure 5-19. Output of Listing 5-20 
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A Simple Drawing Program 

As a practical exercise calculated to draw together many of the topics we've 
discussed in this chapter, we can create a simple, minimal drawing program. 
This program opens a custom screen and a small window. By manipulating 
the mouse and the mouse buttons, the user can either draw a line or move the 
cursor without drawing. A further refinement allows the user to turn the 
draw capability on or off from a menu. As in earlier examples we will spread 
our new functions over several files to implement a structured design. 

Listing 5-21 illustrates the main support function, get_mouse(). This 
function accepts a window reference and traps the significant events within 
that window. These events include the pressing of either mouse button, a 
click on the close window gadget, menu pick event, or even the movement of 
the mouse; each one of these is reported back to the calling function. A 
MOUSEBUTTONS event returns the select code for the specific button 
pushed. A MOUSE MOVE event returns this code as well, but also reports 
the position of the mouse through the reference parameters x and y. A 
MENUPICK returns a flag value to indicate this activity. The specific menu 
item picked is assigned to the mflag parameter. If the user picks the close 
window gadget, the window is closed within the get _mouse( ) function and a 
specific flag value is returned. 

Listing 5-21. Illustrating a get_mouseO function. 



^include <exec/types.h> 

#inc lude <i ntui t ion/intui t ion.h> 

#define EOLU 2 /* define special flags */ 

#define MPICK 9 

USHORT get_mouse(window,x,y, mflag) 

struct Window *window; 

SHORT *x,*y; 

USHORT *mflag; 

{ 

int flag=0; 
USHORT select; 

struct IntuiMessage *msg,*GetMsgO ; /* set up a IDCHP message object */ 
for(;;> < 

Waitd « window->UserPort->mp_SigBit) ; 

whi le((msg=GetMsg(window->UserPort))) { 
switch (msg->Class) { 

case CLOSEWINDOW : ReplyMsg(msg) ; 

f lag=E0LU; 
break; 

case MOUSEBUTTONS : se lect=msg->Code; 

ReplyMsg(msg) ; 

return select; 
case MOUSEMOVE : *x=msg->HouseX; 

*y=msg->MouseY; 

select=msg->Code; 
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/* capture window close */ 
/* mouse button handler */ 
/* the mouse has moved */ 
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Listing 5-21. (cont.) 



RepLyMsg(msg) ; 
return select; 
case MENUPICK : RepLyMsg(msg) ; 

*mf lag=msg->Code; 
return MPICK; 



if (flag == EOLU) { 
C LoseWi ndow(wi ndow) ; 
return EOLW; 

} 
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/* trap a menu choice */ 



/* window close handler */ 



The main!) function for the draw program can be found in Listing 5-22. In 
this function, we must open Intuition, set up and open both a custom screen and 
a window, and set the menu strip in that window. Note the use of the Modify- 
IDCMP( ) system function to prepare the already opened window to report on 
mouse and menu activity. By using this function, we can use our previously 
defined window support function without modifications— another structured 
technique that helps the programmer develop clear, easy to follow code. 

Listing 5-22. An example of a simple drawing program. 



/* include- the menu definitions */ 
/* define some special flags */ | 



^include <exec/types.h> 
^include <intuition/intuition.h> 
^include "m_sup.h" 

#define MPICK 9 
ffdefine EOLW 2 

struct Screen *Screen; 
struct Window *Window; 
void wputsO; 



mainO 
{ 

USHORT f lag,button=SELECTUP,get_mouseO ,item_id=1 ,mf lag, 

i f lags=CLOSEWINDOW | VANI LLAKEY | MOUSEMOVE | HOUSEBUTTONS | MENUP ICK; 
ULONG wflags=WINDOWSIZING] WINDOW DRAG |WINDOWDEPTH| 

WINDOWCLOSE | SHART_REFR£SH | REPORTMOUSE | ACTIVATE; 

SHORT x,y; 
OpenAUO; 

Screen=(struct Screen *) 

make_screen(0,640,200,3,0,1,HIRES,"The Art Show"); 

Window=(struct Window *) 

make_window(20,20,300,100,"Draw or Shoot", wf lags, 0,1 .Screen) ; 
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Listing 5-22. (cont.) 



ModifyIDCHP(Window,if lags); /* set window options */ 

SetMenuStrip(Window,&menu); /* set up the menus */ 

forC;;) { 

if <(f lag=get_mouse(Window,8x,Sy,8mf lag)) == EOLW) < 
CloseScreen(Screen) ; 
exit (TRUE); 

> 

button=(flag == SELECTUP) || (flag == SELECTDOWN) ? flag : button; 
ifCflag == MPICK) /* capture menu events */ 

item_id=ITEMNUM(mf lag); 

if(button == SELECTDOWN && item_id == 0) /* draw option */ 

Draw(Window->RPort,x,y>; 
else ifCbutton == SELECTUP || item_id ==1) /* move option */ 

Move (Wi ndow->RPort , x , y) ; 

> 

> 



The main body of the function is a continuous loop that keeps querying 
the get _mousel ') function. When a window close is reported, the screen is also 
removed and the program ends. MENUPICK and MOUSEBUTTON events 
are also checked for and handled by setting particular flags: button indicates 
the status of the left button and item _ id to carry the last menu choice. 
Compound Boolean expressions containing these flags control calls of the 
Drawl) and Move() functions. Notice that within this program, a 
MOUSEMOVE is treated the same as a MOUSEBUTTONS event— only the 
status of the buttons is noted. 

Listing 5-23. A file containing the setnp for a menu system. 



/* set up the "Draw Disabled" option */ 

struct IntuiText prompt 1 ={6, 7, J AM2, 0,1 , NULL, "Draw Disabled", NULL}; 
struct Menultem d_item=<NULL, 0,11 ,125,9, ITEMTEXT+ITEMENABLED+HIGHCOMP.O, 
(APTR)Spromptl, NULL, NULL, NULL, OxFFFF}; 

/* initialize the "Draw Enabled" menu item */ 

struct IntuiText prompt2={6,7, JAM2,0,1 , NULL, "Draw Enabled", NULL}; 
struct Menultem e_i tem={8d_i tern, 0,0, 120, 10, ITEMTEXT+ITEMENABLED+HIGHCOMP.0, 
<APTR)8prompt2, NULL, NULL, NULL, OxFFFF}; 

/* create the menu structure */ 

struct Menu menu=<NULL, 0,0, 84,0, MENUENABLED, "Opt ions:", &e_i tern}; 
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All of the menu setup information has been exported to a header file, m 
_sup.h. The content of this file is displayed in Listing 5-23. The necessary 
structures are both defined and initialized here. This is a reasonable approach 
and one that can also increase the structure of the program. A program with 
a different menu system can be quickly created just by altering the values in 
this support file. Minimal changes to the rest of the program would be 
necessary. Indeed, if the variable names are the same, it would only be neces- 
sary to recompile the file containing the main(j function and include the other 
files in the linking stage. 

This example program can be used as a springboard for experimenta- 
tion. More functions can be added to enhance its operation. Using the pre- 
viously defined library functions is a good illustration of modular technique. 

Summary 

In this chapter, we have explored the graphics capability of the Amiga, 
available to the programmer through Intuition. We have discussed the three 
graphics objects directly defined within the window interface: borders, In- 
tuiText, and images. This represents a well-behaved interface that is both 
powerful and easy to use. With these objects and their corresponding func- 
tions, powerful graphics displays can be produced. 

The Amiga does not stop with Intuition graphics. The underlying oper- 
ating system software— the Exec ROM kernel— offers a complete graphics 
system, including drawing commands, area fill, and area pattern fill. We have 
explored these graphics functions, as they are accessible through the high- 
level interface Intuition. 
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■ he Amiga offers hardware support for animation; this comes in the 
form of sprites, graphics-oriented displays that can be moved inde- 
pendent of other objects in the display field. The format or the color of sprites 
can also be changed while they are being displayed. Although there are some 
restrictions on the shape and colors that constitute them, sprites offer a 
flexible alternative for movement and animation in a video display. In addi- 
tion to these hardware resources, there is a software subsystem that facili- 
tates the manipulation of the hardware resource. 



Sprites 

A sprite is a hardware object on the Amiga. There are eight special purpose 
DMA (direct memory access) channels that are used to define these graphics 
objects. This means that the drawing of these objects on the screen is inde- 
pendent of the main processor. Sprites can be drawn, moved, changed, and 
redrawn while the CPU is dealing with other tasks. Because they are sup- 
ported directly this way and not built up through layers of software, sprites 
are fast, easy to program, and flexible in their use. 

One of the most striking uses of a sprite— and one that well displays its 
flexibility— is the mouse cursor; this is sprite 0. Using a sprite as the cursor is 
necessary, because the cursor must be available across the entire display and 
not be stopped at window or screen boundaries. The hardware cursor is 
defined outside of all the Intuition objects, so that it can easily move between 
them. This is one example of sprite versatility. Other uses for these objects 
span the obvious and the not-so-obvious. Sprites are available for their tradi- 
tional uses in video games, representing rockets, missiles, and the usual 
panoply of deadly devices. Since the shape of a sprite can be changed while it 
is being displayed, explosions and other forms of mayhem can easily be 
programmed into the display. Sprites can also have more mundane uses. They 
can serve as "paint brush" objects in drawing programs or "follow the bounc- 
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ing ball" pointers in a program devoted to music. There are many unantici- 
pated applications wherein this kind of object can be used to effect. You are 
limited only by imagination. 



Defining a Sprite 

One restriction on the definition of a sprite is that its basic measurements are 
specified in terms of the normal or low-resolution display. The pixel is defined 
as: 

l/320th the width of the screen; and 
l/200th the height of the screen 

However, since these objects are independently supported in hardware, their, 
resolution is unaffected by that of any other objects that are on the display at" 
the same time. Even if these objects change, the sprite remains the same| 
This is not hard to understand if you remember that a sprite is really onlj| 
appearing in front of windows and screens, and is never really a part of them| 

The width of a sprite is also restricted: it may be no more than sixteen? 
pixels wide. A corresponding restriction is not in effect for height, which carg 
be any value up to the full height of the display. Actually, a sprite can be] 
higher than any screen or window that might be displayed behind it. In this: 
case, the sprite must be scrolled to discover its full shape. Beyond these tw~ 
restrictions, any shape that can be rendered into a space sixteen pixels wid 
can be implemented as a sprite. 

The shape of a sprite is specified in memory as a set of contiguous 16-bitf 
locations (Figure 6-1). The first two locations are reserved for hardware coin 
trol instructions and represent the values to be put into the hardware regis; 
ters associated with the sprite. The last two locations are also used f 
control. The body of this array is used to define the shape of the sprite. Ea^ 
line is represented by two locations in memory. Each pixel in the display * 
defined by a pair of bits— one from each of the two words (Figure 6-2). Thf" 
pair of bits indicates the color that a particular pixel will be. The colorj!^ 
specified indirectly through one or more color registers; these kinds of coM 
specification will be discussed in more detail later. 

The memory locations that define the sprite image are accessibt 
through an array of 16-bit integers; either USHORT or UWORD will wor!' 
Typically, the appropriate values are indicated using hexadecimal number, 
since these make it easy to translate from bit positions to a numeric for 
that the system can understand. Figure 6-3 shows a typical way to create^ 
sprite. First you create the figure in some convenient form such as grap, 
paper. Once you have a form that you like, you can then translate each line 
your drawing into a four-digit hexadecimal number (recall that four bi 
translate to one hexadecimal digit). Specification of the second word definffi 
the line is a function of the color that you want for the individual pixel. 

We mentioned earlier that the mouse cursor is actually a sprite. In, 
ition offers a function that allows you to change the shape of this cursor. Tt 
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Figure 6-1. The format of a sprite definition in memory 
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Figure 6-2. Defining the sprite image 
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Listing 6-1. (cont.) 



0x0000,0x0000 }; 

#define INTUITION_REV 29 
fldefine GRAPHICS_REV 29 

mainO 
{ 

SHORT x.y.w.h.d; 
USHORT mode; 
UL0NG flags; 
UBYTE cO.d; 

VOID delay. funcO .OpenALLO ; 

OpenALLO; /* Error checking could be added here */ 
======open a hi-res custom screen==== */ 

y=0; 

w=640; 
h=200; 
d=3; 

c0=0x00; 
c 1=0x01; 
mode=HIRES; 

'""""S screen Cy' W,h,d,c0,c1 .mode , "TEST SCREEN") ; /. Error checking 
could be added here */ 

/* ===Open a window=== */ 

x=10; 
y=10; 
w=300; 

nag 1 s=°CTIVATE|SHART.REFRESH|UINDO«SIZING|WINDOWCLOSE|WINDOW0RAG; 

c0=-1 ; 
d=-1; 

wind=(struct Window *) 

make.windowCx.y.w.h, "Window 0",f lags. cO.d .Scrn, NULL) ; 

/* ===create and set a new pointer=== */ 
SetPointeKwind, imp_data,16,16,0,0) ; 
Delay<500); 

/* =========Close down the window then the screen==========*/ 

CloseScreen(Scrn) ; 

} 



Listing 6-1. (cont.) 



Chapter 6 



VOID de Lay_func (factor) 
int factor; 

/* This function will cause a specified delay */ 
int loop; r 

'I ' 
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for( loop=0; loop<f actor*1000; loop++) 
return; 



} 



Color and the Sprites 

We alluded to the fact that each pixel in the sprite is assigned a value that 
points to a color register. This indirect color addressing is the same through- 
out the Amiga for any kind of graphic image rendering. There is, however, a 
limitation on the sprite that is not found in the pure graphics routines. Each 
particular sprite is associated with a specific set of four-color registers. Each 
pixel in the sprite can take on one of three colors, or it can be transparent. In 
this latter case, the appearance of the sprite— or parts of the sprite— allow 
other objects to show through it. This allows the designer to make the sprite 
appear as if it were going behind an object. Recall that this object type is 
completely independent of windows and screens, and can contain no gadgets. 
Transparency is a way to capture the same kind of action that a window or 
screen provides with the Depth Arrangement Gadget. 

Figure 6-5. Indirect addressing of color registers 

Color register 0 

Color register 1 
Color register 2 
Color register 3 



word 2 ^0 
word 1 0 
word 2 1 - 
word 1 0 
word 2 ^0- 
word 1 1 
word 2 1 - 
word 1 S 



The color register identifier is encoded in the 2-bit specification for each 
pixel. (Recall that the sprite data array required two integers to define a 
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single line of the figure.) The 0 bits of each word are taken together, the 1 
bits, and so on down to the sixteenth position. Within the three-color con- 
straint, each pixel's color is independent of its neighbors. Figure 6-5 indicates 
how these color values are encoded. 

Thirty-two color registers are available on the Amiga, numbered from 0 
to 31. Each of these registers may specify any of the 4096 possible colors that 
can be produced. Any or all of the registers may be used by the graphics 
objects found in the display; this is a function of the specified depth of these 
objects. Sprites are assigned to the color registers 16 through 31; they do not 
necessarily have exclusive use of these registers. This is dependent on what is 
being displayed concurrently and the number of bit planes allocated. Some 
registers have to be shared with windows, screens, or pictures. Figure 6-6 
indicates the specific assignment of registers to sprites. 

Figure 6-6. Sprite color register map 
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There is a further complication. Sprites are divided into pairs, and each 
pair must share a register set. Setting a particular set of colors for sprite 0, 
for example, means that you are also setting the same colors for sprite 1. 



The SimpleSprite 

So far, you have seen how to specify the shape of a sprite, how to set the 
colors of its pixels, and what kind of memory organization the hardware 
expects. The Amiga also offers a software subsystem that lets you easily set 
up and manipulate these objects through C programs, without requiring 
access of the hardware register locations or even assembly language pro;: 
gramming. This subsystem consists of the SimpleSprite structure and «j 
series of system functions that manipulate it. This structure exists in addi-l 
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tion to the array definition already used to good effect in the SetPointeri) 
function. There are two system macros: 

ON_SPRITE 
OFF_SPRITE 

These macros switch the sprite display circuitry on and off. The default 
condition is ON_SPRITE, so this need never be explicitly mentioned unless a 
previous execution of OFF _ SPRITE has made the sprites invisible. These, 
along with other necessary declarations, are found in the header file graphics/ 
sprite.h. 

A SimpleSprite is defined by its structure declaration: 

zero 

zaragoza 

posctldata points to position control values in memory, 
height indicates the number of lines in the sprite. 
x,y set the sprite's current position in the display area, 
num also contains hardware-specific information. 

This is a very simple data type, particularly since only height, x, and y are set 
by the user. The other two members of the structure are set solely by the 
machine. 

Once you have declared a SimpleSprite variable, you must ask the sys- 
tem to allocate a sprite for your use. This, too, is done through a system 
function: 

spri te_id=GetSpri te(s_pt r, s_number) ; 
where 

sprite_id is the number of the sprite allocated by this function. 

s_ptr points to a SimpleSprite structure. 

s_ number indicates the number of the sprite desired. 

A call to this function initializes the structure and prepares it to participate 
in the other sprite functions. If you specify —1 for the s_number parameter, 
the system assigns the next available sprite. In contrast, if you ask for a 
specific sprite, that one is allocated. If it is not available, the functions return 
— 1 to indicate an error condition. This value is also returned if there are no 
sprites left to allocate. 

Once a sprite has been allocated, it is necessary to set the desired values 
into the defining structure and to attach it to the image data. Setting the 



struct SimpleSprite { 
UWORD *posct Ldata, 
height , 

x,y. 
num; 

>; 



where 
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initial values is easily accomplished by explicitly assigning values to the x,y, 
aid height members. The x and y assignment set the initial position of the 
sprite. The height assignment must be consistent with the layout of the 
image data. Once you have made the height assignment— this is the only one 
that is strictly necessary— you can call the system to attach the data and 
sprite. This is done with: 

ChangeSpri te (v_port ,s_st ruct , s_data) 
where 

v_port is a pointer to the ViewPort of the display area. This is 
commonly set to 0 to indicate the current value. 
s_ struct points to the SimpleSprite structure. 
s_data is a pointer to the image data. 

This function can be used again to change an existing sprite, by attaching 
new image data array to it. The shape, the color, or both may be changed. The 
new sprite is visible immediately. 

Besides adjusting a sprite's shape and color, it is also necessary to move 
it around the display. This is done by a call to: 

MoveSpri te(v_port , s_num,x,y) 

V_port is a pointer to the ViewPort of the display area or to 0 to indicate the 
current one. This function moves the sprite to the location x,y on the display 
area. These coordinates are relative to the overall coordinates of the displayed 
ViewPort; this can be either a window or a screen. Figure 6-7 illustrates this 
relationship. Again, even if you specify a location in relation to a window, the 
sprite is still an independent hardware object, not really a part of that window. 

Listing 6-2 px-oduces a multicolored sprite and causes it to move back , 
and forth diagonally on the display screen. After calling GetSpritef) tog 
allocate the next available sprite, we check to make sure that the function 
was successful; if it was not, we exit. Next we initialize the SimpleSprite 
structure, imp. Here the critical value is setting imp. height to 9 to make it 
compatible with the data in the imp_data array. The switch statement is set 
up to discover which sprite was assigned to the s_id variable. This variable f 
sets the variable k to the corresponding color register value. 

Listing 6-2. Allocating and playing with a hardware sprite. 



tf-nclude <exec/types . h> 

#inc lude <intui t ion/ intuit ion. h> 

^include <graphi cs/spri te.h> 

struct Screen *Scrn; 
struct Window wind; 
struct SimpleSprite imp; 

UUORD imp_dataC]= < 
0,0, 
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Figure 6-7. The position of a sprite relative to a ViewPort 
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Listing 6-2. (cont.) 



0x0fc3, 0x0000, 
0x3ff3, 0x0000, 
0x30c3, 0x0000, 
0x0000, 0x3c03, 
0x0000, 0x3fc3, 
0x0000, 0x03c3, 
0xc033,0xc033, 
Oxf fcO.OxffcO, 
0x3f03,0x3f03, 
0,0 }; 



nai nO 

{ 

SHORT x,y,w,h,d,s id,k,xmove,ymove,n,i ; 

USHORT mode; 

ULONG flags; 

UBYTE *name,c0,d ; 

VOID delay_func(),0penALLO; 

OpenALLO; /* Error checking could be added here */ 

/* ======0pen a hi-res custom screen==== */ 

y=0; 

w=640; 
h=200; 
d=3; 

c0=0x00; 
d=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h, d,cO,d .mode, NULL) ; 

ShowTitle(Scrn, FALSE); 

/* ===0pen a backdrop window=== */ 

name=NULL; 

x=0; 

y=0; 

w=640; 

h=200; 

f lags=ACTI VATE | SMART_REFRESH | BORDERLESS | BACKDROP; 

c0=-1 ; 

d=-1; 

wind=(struct Window *) 

make_w i ndow ( x,y,w,h, name, f lags, cO,d ,Scrn,NULL) 

/* ===Create and play with a simple hardware sprite=== 

i f((s_id=Get Sprite (Simp, -1))==-1) 
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Listing 6-2. (cont.) 



exitO; 

imp.x=0; 
i mp . y=0 ; 
imp.height=9; 

switch(s_id) { 
case 0: 
case 1 : k=16; 

break; 

case 2: 

case 3: k=20; 

break; 

case 4: 

case 5: k=24; 

break; 

case 6: 

case 7: k=28; 

break; 

> 



SetRGB4(SScrn->ViewPort,k+1 ,12,3,8); 
SetRGB4 (&Scrn->Vi ewPort , k+2 , 13, 13,13) ; 
SetRGB4(&Scrn->ViewPort,k+3,4,4,15) ; 

ChangeSpri te (&Scrn->Vi ewPort ,Si mp , Si mp_dat a) ; 

MoveSprite(0,8imp,30,0) ; 

xmove=1 ; 
ymove=1 ; 

for(n=0;n<4;n++) { 
i=0; 

whi le(i++< 185) { 

MoveSpri te(0, Simp, imp. x+xmove, imp. y+ymove) ; 
WaitTOFO; 

} 

ymove=-ymove; 
xmove=-xmove; 

> 

FreeSprite(s_id) ; 
/* =========c lose down the window then the screen========*/ 



C loseScreen(Scrn) ; 



VOID delay_func(factor) 



J? 
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Listing 6-2. (cont.) 



nt factor; 

!* This function will cause a specified delay */ 

C 

int loop; 

for(loop=0; Loop<f actor*1000; Loop++) 
return; 

> 



Once our program has completed its initialization, we are ready to be 
creative with the sprite. We first set the colors of the three registers associ- 
ated with our current choice; this is done by a call to: 

SetRGB(v_port ,c_reg, red, green, blue) ; 
where 

v_port is a pointer to the active ViewPort. 
c_reg identifies the particular color register. 

red. green, and blue set the values for these respective colors in that 
register. 

The three primary color variables take on values between 0 and 15. 
These values represent the proportion of that particular color that will be 
mixed into the color to be associated with a particular register. In our exam- 
ple, we use the screen ViewPort. 

Once we have set the colors that the sprite' data will use, we execute 
ChangeSpritef ) to associate these colors with the data defined in imp_dataf]^ 
We initially move the sprite to location 30,0 by a call to MoveSpriteO, and 
enter a loop. The loop continues to move the sprite by an increment of one 
through the variables xmove and ymove. By changing the sign of ymove ok 
every loop, we cause the sprite to move back and forth. The heart of this inner 
loop is the MoveSpriteO function call, but we also include a WaitTOFO com- 
mand. It suspends the move until the next draw cycle (actually the video 
blanking period). This delay tends to make a smoother appearing program. 
The FreeSpriteO function takes the sprite identifier as a parameter and de- 
allocates the memory assigned to it. It is always necessary, when using the 
Amiga, to relinguish resources no longer needed. 

Listing 6-3. Allocating and playing 
with improved hardware sprites. _| 



#include <exec/types.h> 
^include <intuition/intuition.h> 
^include <graphics/sprite.h> 
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Listing 6-3. (cont.) 



struct Screen *Scrn; 
struct Window wind; 
struct SimpleSprite imp; 

UWORD imp_datal]= { 
0,0, 

0x0180,0x0000, 
0x03c0, 0x0000, 
0x07e0, 0x0000, 
0x0e70, 0x0000, 
0x1c38, 0x0000, 
0x381c, 0x0000, 
0x718e, 0x0000, 
0xc3c3, 0x0000, 
0xc3c3, 0x0000, 
0x718e, 0x0000, 
0x381c, 0x0000, 
0x1c38, 0x0000, 
0x0e70, 0x0000, 
0x07e0, 0x0000, 
0x03c0, 0x0000, 
0x0180,0x0000, 
0,0 >; 



ma i n ( ) 
{ 

SHORT s i d,x,y,w,h,d, xmove, ymove, n, i ; 

USHORT mode; 

ULONG flags; 

UBYTE *name,c0,d; 

VOID delay_func() .OpenALLO; 

OpenALLO ; 

/* ======open a hi-res custom screen==== */ 

y=0; 
w=640; 
h=200; 
d=3; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,cO,d , mode , NULL) ; 

ShowTi tle(Scrn, FALSE) ; 

/* ===open a backdrop window=== */ 

name=NULL; 
x=0; 



2 4 



G 0 



o 



227 



Animating the Sprites 



Listing 6-3. (cont.) 



y=0; 

w=640; 
h=200; 

f Lags=ACTIVATE | SMART REFRESH | BORDERLESS | BACKDROP; 

c0=-1 ; 

d=-1; 

wind=(struct Window *) 

ma ke_w i ndow ( x,y,w,h, name, f lags, cO,d ,Scrn,NULL) 

/* ===C reate and play with a simple hardware sprite=== 

init_sprite(8imp,8s_id); 

ChangeSpri te (8Scrn->Vi ewPort ,8imp,8imp_data) ; 

MoveSprite(0, Simp, 30,0) ; 

xmove=1 ; 
ymove=1 ; 

for(n=0;n<4;n++) ( 
i=0; 

whi le(i++< 185) I 

MoveSpri te (0,8 imp, i mp. x+xmove , i mp. y+ymove) ; 
WaitTOFO ; 

} 

ymove=-ymove; 

> 

FreeSprite(s_id) ; 
/* =========ciose down the window then the screen===== 



CloseScreen(Scrn) ; 



init_sprite(imp,s_id) 
struct SimpleSprite *imp; 
SHORT *s id; 

{ 

SHORT k; 

if C(*s i d=Get Sprite (Si mp,-1))==-1) 
exitO; 

i mp->x=0; 
i mp->y=0; 
imp->height=16; 

switch(*s_id) { 
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Listing 6-3. (cont.) 



case 0: 

case 1 : k=16; 

break; 

case 2: 
case 3: k=20; 

break; 

case 4: 
case 5: k=24; 

break; 



case 6: K 



^ 1] 



Ay 



^ 

case V: k=28; ^ ^ 4 

break; 

> 

SetRGB4(8Scrn->ViewPort,k+1 ,12,3,8); 
SetRGB4 (8Scrn->ViewPort,k+2, 13, 13,13), • 
SetRGB4(8Scrn->ViewPort,k+3,4,4,15) ; 



VOID delay_func(factor) 
int factor; 

/* This function will cause a specified delay */ 
int loop; 

for( loop=0; loop<factor*1000; loop++) 



return; 

> 



The code in Listing 6-3 produces a display similar to the first example. 
The program is improved in two ways: 

1. All initialization has been gathered together in a single function, init_ 
sprite!). 

2. The sprite image has been redesigned to a more pleasant form and 
increased in size to 16 by 16. 

The function definition makes this example a more modular program in com- 
parison to Listing 6-2. 

In Listing 6-4, we allocate and manipulate two separate sprites. Notice 
that we use the same image data to define each one, but we initialize them 
independently and have two sets of commands for each. The program moves 
the sprite around on the display screen. There must be a separate call to 
FreeSpriteO for each sprite defined. 
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Listing 6-4. Allocating and playing with two hardware sprites. 



#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <graphi cs/spri te.h> 

struct Screen *Scrn; 

st~uct Window wind; 

st"uct SimpleSprite imp0,imp1; 

UWORD imp dataC]= { 
0,0, 

0x0180,0x0000, 
0x03c0, 0x0000, 
0x07e0, 0x0000, 
0x0e70, 0x0000, 
0x1c38, 0x0000. 
0x381c, 0x0000, 
0x718e, 0x0000, 
0xc3c3, 0x0000, 
0xc3c3, 0x0000, 
0x718e, 0x0000, 
0x381c, 0x0000, 
0x1c38, 0x0000, 
0x0e70, 0x0000, 
Ox07eO, 0x0000, 
0x03c0, 0x0000, 
0x0180,0x0000, 
0,0 >; 



mainO 
{ 

SHORT s_id0,s id1 ,x,y,w,h,d,xraove0,ymove0,xmove1 ,ymove1 ,n,i ; 
USHORT mode; 
ULONG flags; 
UBYTE *name,c0,d; 
VOID de lay_f unc () , OpenALLO ; 

DpenALLO ; 

/* ======open a hi -res custom screen==== */ 

y=0; 

n=640; 
h=200; 
d=3; 

c0=0x00; 
d=0x01 ; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 .mode, NULL) ; 

ShowTi t LeCScrn, FALSE); 



Z B B O 

ZARAGOZ A 
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Listing 6-4. (cont.) 



/* ===0pen a backdrop window=== */ 

name=NULL; 

x=0; 

y=0; 

w=640; 

h=200; 

f lags=ACTIVATE | SMART_RE FRESH | BORDERLESS | BACKDROP; 

c0=-1 ; 

c1=-1; 

wind=(struct Window *) 

make_wi ndow(x,y,w,h, name, f Lags, cO.d ,Scrn,NULL) ; 

/* ===Create and play with a simple hardware sprite=== */ 

init_spri te(8imp0,&s_id0) ; 

ChangeSprite(8Scrn->ViewPort,8impO,8imp_data) ; 
MoveSpri te(0,8imp0,30,0) ; 
init_sprite(8imp1 ,8s_id1 ) ; 

ChangeSprite(8Scrn->ViewPort,8imp1 ,8imp_data) ; 

MoveSpri te(0,8imp1 ,35,10) ; 

xmove0=1 ; 
ymove0=1 ; 
xmove1=1 ; 
xmove1=1 ; 

for(n=0;n<4;n++) i 
i=0; 

while(i++< 185) i 

MoveSpri te(0,8imp0, impO.x+xmoveO, impO.y+ymoveO) ; 
WaitTOFO; 

MoveSprite(0,8imp1 ,imp1 .x+xmove1 , imp1 .y+ymove1) ; 
WaitTOFO; 

} 

ymoveO=(-ymoveO) ; 
ymove1 = (-ymove1 ) ; 

} 

FreeSprite(s_idO) ; 
FreeSprite(s_id1); 

/* =========Close down the window then the screen========*7 



CloseScreen(Scrn) ; 
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Listing 6-4. (cont.) 



> 

init_sprite(imp,s_id) 
struct SimpleSprite *imp; 
SHORT *s_id; 
< 

SHORT k; 

if ((*s_id=GetSprite(&imp,-1))==-1) 
exitO; 



i mp->x=0; 
i mp->y=0; 
irap->height=16; 



swi tch ( 


*s 


.id) { 


case 


0:' 




case 


1 : 


k=16; 






break; 


case 


2: 




case 


3: 


k=20; 






break; 


case 


4: 




case 


5: 


k=24; 






break; 


case 


6: 




case 


7: 


k=28; 






break; 



> 



Set RGB4(&Scrn->ViewPort,k+1 ,12,3,8) ; 
SetRGB4(&Scrn->ViewPort,k+2,13,13,13) ; 
Set RGB4(8Scrn-> ViewPort ,k+3,4,4,15) ; 

} 



/OID de Lay_func (factor) 
int factor; 

!* This function will cause a specified delay */ 

C 

int loop; 

for( loop=0; loop<factor*1000; loop++) 



return; 
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Up until now the only thing you have done with sprites is to move them 
around the screen. You are not restricted to this activity. By creating a loop, 
you can continuously change any of the parameters of the object. In Listing 
6-5, we not only move a sprite, but we periodically change its shape. Notice 
that we have two independent image data arrays. Each array defines a differ- 
ent shape for the sprite. To make a shape change, all we need to do is call 
ChangeSpritei ) and pass it the new image data array. Our example makes 
such a shape change controlled by the outer for loop. Each time this loop is 
incremented, a call to ChangeSpritei) switches the sprite from its current 
shape to that defined by the other image data array. On even-numbered loops, 
we use imp_datal, and on odd-numbered loops, imp _dataO. The inner loop 
merely moves the sprite around the display. 

Listing 6-5. Changing the shape of a hardware sprite. 



(/include <exec/types.h> 
#include <intuition/intuition.h> 
^include <graphi cs/spri te. h> 

struct Screen *Scrn; 

struct Window wind; 

struct SimpleSprite imp0,imp1; 



UWORD imp dataOC]= < 
0,0, 

0x07e0, 0x0000, 
0x0810,0x0000, 
0x1008,0x0000, 
0x2004,0x0000, 
0x4c32, 0x0000, 
0x9e79, 0x0000, 
0x8c31 ,0x0000, 
0x8001 ,0x0000, 
0x8001 ,0x0000, 
0x8001 ,0x0000, 



FOR 



2AR A60Z A 



0x9009,0x0000, f_ JL, 

0x4812,0x0000, ^ ]g "|p> 



0x27e4, 0x0000, *- 4 *!, 

0x1008,0x0000, 
0x0810,0x0000, 
0x07e0, 0x0000, 
0.0 >, 

imp datal []={ 

o.oT 

0x07e0, 0x0000, 
0x0810,0x0000, 
0x1008,0x0000, 
0x2004,0x0000, 
0x4c32, 0x0000, 
0x9e79, 0x0000, 
0x8c31 ,0x0000, 
0x8001 ,0x0000, 
0x8001,0x0000, 
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Listing 6-5. (cont.) 



0x8761,0x0000, 
0x8811 ,0x0000, 
0x500a, 0x0000, 
0x2004,0x0000, 
0x1008,0x0000, 
0x0810,0x0000, 
0x07e0, 0x0000, 
0,0}; 



mai n () 
{ 

SHORT s_id,x,y ,w,h,d, xmoveO , ymoveO , n , i ; 

USHORT mode; 

ULONG flags; 

U8YTE *name,c0,d; 

VOID de lay_f unc () ,0penALL() ; 

OpenALLO ; 

/* ======open a hi-res custom screen==== */ 

y=0; 
w=640; 
h=200; 
d=3; 

c0=0x00; 
c1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen<y ,w,h,d,c0, c1 , mode, NULL) ; 

ShowTit leCScrn, FALSE); 

/* ===o P en a backdrop window=== */ 

name=NULL; 

x=0; 

y=0; 

w=640; 

h=200; 

f Lags=ACTIVATE | SMART_REFRESH | BORDERLESS | BACKDROP; 

c0=-1; 

d=-1; 

wind=(struct Window *) 

ma ke_w i ndow ( x,y,w,h, name, f Lags, cO,d ,Scrn,NULL) ; 

/* ===Create and play with a simple hardware sprite=== */ 

init_sprite(8imp0,8s_id,0, 0,0,0) ; 

ChangeSpri te(0,8imp0,8imp_data0) ; 
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Listing 6-5. (cont.) 



MoveSprite(0,8imp1 ,35,10); 

xmove0=1 ; 
ymove0=1 ; 

for(n=0;n<4;n++) { 
i=0; 

whi Le(i++< 185) { 

HoveSpri te(0,8i mpO, i mpO. x+xmoveO, i mpO.y+ymoveO) ; 
WaitTOFO; 

> 

if ((n%2)==0) 

ChangeSpri te(0,8imp0,8imp_data1) ; 
else 

ChangeSpri te(0,8i mp0,8i mp_data0) ; 
ymoveO=<-ymoveO) ; 

> 

FreeSprite(s_id) ; 
/* =========c Lose down the window then the screen========*/ 



C LoseScreen(Scrn) ; 

> 

init_sprite(imp,s_id,s_num, r,g,b) 
struct SimpleSprite *imp; 
SHORT *s id,s_num; 
USHORT rTb.g; 
{ 

SHORT k; 

i f ((*s id=GetSpri te(8imp,s_num))==-1) 
exitb; 

imp->x=0; 
imp->y=0; 
i mp->hei ght=1 6; 

switch(*s_id) { 
case 0: 
case 1 : k=16; 

break; 

case 2: 
case 3: k=20; 

break; 

case 4: 
case 5: k=24; 

break; 

case 6: 

235 



k 4 



Animating the Sprites 



Height, Width, Depth— which define these values for the virtual 
sprite; 

SprColors— which contains a pointer to the color information; 
ImageData— which defines the shape of the sprite. 

These values must be initialized by the program before the VSprite is put 
onto the GELs list. Since this object is restricted to a width of sixteen pixels, 
the Width member is always 1. Height is specified as the number of lines that 
the sprite object will occupy. As with hardware sprites, the maximum height 
can be the full size of the display. The Depth is the number of bit planes the 
image occupies. For a virtual sprite this parameter is always two. 

The SprColors member must be set to point to an array of sixteen bit 
integers. These integers represent the three colors available to the virtual 
sprite. Each integer contains an intensity value— 0 to 15— for each of the 
basic colors. This format is illustrated in Figure 6-9. 

Figure 6-9. SprColors format 

0x0 <red><green><blue> 

l — 0-15 (intensity) 
— 0-15 (intensity) 
— 0-15 (intensity) 

The shape of the VSprite is also defined by an array of sixteen-bit words. The 
bit positions in these words define which of the possible colors will be used to 
draw a particular pixel in the image. Since a VSprite always has a depth of W 
it takes two words to define each line of the object. These two lines are 
matched bit by bit. A particular color register is then associated with a 
specific pixel. This mechanism is illustrated in Figure 6-10. For a VSprite 
pixel, there are four possible combinations: 

00 this defines a transparent pixel— one that does not appear; 

01 this points to color register one; 

10 this points to register two; 

11 and this to register three. 

It should be noted that these numbers do not refer to an absolute color; 
register but only those associated with the hardware sprite that will implfrs 
ment them. The particular values for each of these references was set by the 
SprColor field in the structure. 

Once a VSprite variable has been declared and initialized, it must be 
added to the GEL system's linked list; this is done through the system call 
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Figure 6-10. Format for a VSprite image 




VWORD data[ | = { 0X000O, 0X1111, 
0X1011. 0X0000, 
0 X0000, 0X0101, 
0X1101. 0X1111, 



Each line of the image is defined by two words from the array: 



■ color register 2 
■ transparent 
1111000011110000 

t t 

0000000000000000 

t t 



AddVSpriteCv.r) 

where v is a pointer to the VSprite variable that we've just created and r is 
the address of the RastPort of the display object with which the Gelslnfo 
structure is associated. This adds the new VSprite to the list but doesn't 
prepare it for display. A call to this function must be included for each 
VSprite that is to be displayed, but the call must be done only once for each of 
VSprite. A complementary system call 

RemVSpn'te(v) 

will remove a particular virtual sprite from the list. As with AddVSprite( ), v 
is a pointer to the particular VSprite variable to be removed. 



Displaying a GELs List 

So far we have been concentrating on defining our GELs system objects and 
adding them to the display list. However, merely adding them to the list is 
not sufficient to cause them to appear on the monitor screen. There are 
several steps that must be performed before we can see our handiwork danc- 
ing on the display. The goal of these steps is to prroduce a set of instructions 
for the Amiga's custom hardware. The GELs system reduces this complex 
task to a series of system calls. 

The first task is to sort the GELs list. The display hardware paints the 
monitor screen from left to right and from top to bottom. It's necessary that 
the objects on the GELs list be arranged in this order— as a particular part of 
the display is drawn, reference to the list will be made to see what else must 
be put in the display. This sorting is accomplished by 

SortGList(r) 

where r points to the display's RastPort. This routine uses the X and Y 
members to make its arrangements. 
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Listing 6-6. (cont.) 



c0=-1 ; 
d=-1; 

*ind=(struct Window *) 

make_wi ndow(x,y,w,h, name, f lags, cO,d ,Scrn,NULL); 

I* initialize the Gelslnfo structure */ 

ginfo. next Li ne=(W0RD *) A I LocMeraCsi zeof (WORD) *8,MEHF_CHIP |MEMF_CLEAR) ; 
ginfo. lastColor=(WORD **) AL LocMemCsi zeof (LONG) *8,MEMF_CH IP | MEMF_CLEAR) ; 
ginfo.sprRsrvd=Oxfc; 



/* initialize the VSprite structure */ 
vimp.Height=16; 
vimp.Width=16; 
vimp.Depth=2; 
vimp.SprColors=colors; 
vimp. ImageData=vi mp_data; 
vimp.X=25; 
vimp.Y=25; 
vimp.Flags=VSPRITE; 



2ar 



Mat 

H o 



/* set up the Gelslnfo system */ 
wind->RPort->GelsInfo=&ginfo; 



/♦...and a the right one 



/* attach the Gelslnfo to the current */ 
/* RastPort */ 
InitGels(Svhead,&vtai l.Sginfo); /* initialize it */ 

AddVSprite(8vimp,wind->RPort) ; /* add the VSprite to the list */ 
x=y=25; 

for(i=0;i<5000;i++) { /* move the VSprite around */ 

if(x < X LF BORDER) { /* change direction at the left nand border * 
x=X_LF_i0RDER+1; 
xin=1 ; 

> 

else if( x > X_RT_BORDER) { 
x=X_RT_B0RDER-1 ; 
xin=(-T) ; 

> 

else 
x+=xin; 

if(y < Y_TP_BORDER) < 
y=Y_TP_B0RDER+1 ; 
yin=1; 

> 

else if(y > Y_BT_B0RDER) < 
y=Y BT BORDiR-T; 
yin=(-T>; 

> 

else 

y+=yin; 



/* move down at the top *f 



I* move up at the bottom 9 



vimp.X=x; 
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Listing 6-6. (cont.) 



vimp.Y=y; 



SortGList(wind->RPort) ; 

DrawGLi st (wi nd->RPort ,8(Scrn->Vi ewPort) ) ; 
MakeScreen(Scrn) ; 
Rethi nkDi splayO ; 
WaitTOFO; 



/* sort and redisplay */ 
/* the VSprite */ 



CloseWindow(wind) ; 
CloseScreen(Scrn) ; 



/* close down the window */ 
/* and the screen */ 



Listing 6-6 shows a simple VSprite example. This program will cause a 
single virtual sprite to bounce back and forth on the screen. Besides the 
necessary definitions and declarations for a window and a screen, four bound- 
ary constants are defined. These constants will be used later to control the 
movement of the sprite. Three VSprite variables are declared: vhead and vtail 
to define the GELs list, and vimp which will create a moving sprite. A single 
Gelsinfo structure, ginfo, is also declared. The two ginfo members, nextLine 
and lastColor, are allocated and the sprRsrvd member is initialized to elimi- 
nate hardware sprites 0 and 1 (to avoid any conflict with the mouse pointer). 
Next the appropriate values are put into the VSprite structure, vimp. Note 
that we must set the flags member of this latter structure to the flag value 
VSPRITE. This same structure will be used later to define a Bob. Please note 
that it is necessary to distinguish these two uses. Finally, the ginfo structure 
is attached to the RastPort of the window, a call to InitGelsO creates the 
GELs list, and the VSprite structure is added to the list. 

The basic operation of the program in Listing 6-6 is to move the VSprite 
across the screen on pixel at a time. At each move a check is mode to see if the 
sprite is at a boundary: if it is, the direction of movement is changed and the 
program continues. Each time this movement calculation is performed, the 
vimp variable is updated and the display sequence is performed. WaitTOFf ) is 
a system call that will cause the program to wait until all the changes have 
been performed. 

Listing 6-7. The VSprite support library 



#include <exec/types.h> 
#inc lude <intui t ion/i ntui t ion.h> 
#include <graphi cs/rastport . h> 
^include <graphics/sprite.h> 
#include <graphics/gf xmacros.h> 
^include <graphics/gels.h> 
^include <graphi cs/vi ew.h> 
Sinclude <exec/memory.h> 

/* s_display() will redraw and display the Gelslnfo system. */ 
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Listing 6-7. (cont.) 



s_display(w,s,vsp) 
struct Window *w; 
struct Screen *s; 
struct VSprite *vsp; 

SortGListCw-^PortJ; /• sort and redisplay */ 

DrawGList(w->RPort,8(s->ViewPort)); /* the VSprite */ 

MakeScreen(s) ; 
RethinkOisplayO; 
WaitTOFO; 

> 

/* g initO will initialize the Gelslnfo system. */ 

g_init(w,vhead,vtai l.ginfo) 
struct Window *w; 
struct VSprite *vhead,*vtai I; 
struct Gelslnfo *ginfo; 

{ qinfo->nextLine=(WORD *) A I locMem(si zeof (WORD) *8,MEMF_CHIP | MEMF_CLEAR) ; 
ginfo->lastColor=(WORD **) A I locMemCsi zeof (LONG) *8 ,MEMF_CH IP | MEM F_C LEAR) ; 
ginfo->sprRsrvd=0xfc; 

/* set up the Gelslnfo system */ 

w->RPort->GelsInfo=ginfo; /* attach the Gelslnfo to the current */ 

/* RastPort */ 
InitGels(vhead,vtail.ginfo); /* initialize it */ 

> 



The initialization for the Gelslnfo structure must be performed for eacfaj 
GELs list. Note that the basic display sequence is common to all the amma^ 
tion programs. The Gelslnfo initialization and the basic display sequence are. 
prime candidates for exportation to a user defined library of animation sup-j 
port routines. Listing 6-7 shows the contents of such a library file. The S3 
display!) routine takes a pointer to a window, a screen, and a VSprite and 
performs the rendering sequence using these objects. G_init() initializes the, 
Gelslnfo structure that is passed as a parameter creating a GELs list with its 
Other two parameters as head or tail. Putting this code in independent func- 
tions will yield modules that manipulate more than one VSprite. 

Listing 6-8. A VSprite program that makes changes to 

the VSprite. l| 



^include <exec/types.h> 
^include <intuition/intuition.h> 
Sinclude <graphi cs/rastport . h> 
^include <graphics/sprite.h> 
ffinclude <graphics/gfxmacros.h> 
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Listing 6-8. (cont.) 



^include <graphics/gels.h> 
Sinclude <graphics/view.h> 
#include <exec/memory.h> 



#define Y BT BORDER 183 
#define Y TP BORDER 1 
#define X RT BORDER 605 
(Kdefine X LF BORDER 1 



/* set some constants to control the VSprite */ 
/* movement — quite arbitrary */ 



struct Screen *Scrn; 

struct Window *wind; 

struct VSprite vimp,vhead,vtai I; 

struct Gelslnfo ginfo; 

USHORT colorsn={0x0e30,0xffff ,0x0b40}; /* set the VSprite color range */ 



UWORD vimp_dataOn= < 

0x07e0,0x07e0, 
0x0810,0x0810, 
0x1008,0x1008, 
0x2004,0x2004, 
0x4c32,0x4c32, 
0x9e79,0x9e79, 
0x8c31 ,0x8c31 , 
0x8001 ,0x8001 , 
0x8001 ,0x8001 , 
0x8001 ,0x8001 , 
0x9009,0x9009, 
0x4812,0x4812, 
0x27e4,0x27e4, 
0x1008,0x1008, 
0x0810,0x0810, 
0x07e0,0x07e0>, 
vimp_data1 []={ 

0x07e0,0x07e0, 
0x0810,0x0810, 
0x1008,0x1008, 
0x2004,0x2004, 
0x4c32,0x4c32, 
0x9e79,0x9e79, 
0x8c31,0x8c31, 
0x8001 ,0x8001 , 
0x8001 ,0x8001 , 
0x87e1 ,0x87e1 , 
0x8811 ,0x8811 , 
Ox500a,Ox500a, 
0x2004,0x2004, 
0x1008,0x1008, 
0x0810,0x0810, 
0x07e0,0x07e0>; 



/* the image data that defines the VSprite */ 



sinO 
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Listing 6-8. (cont.) 



SHORT x,y,w,h,d,i; 

USHORT mode; 

ULONG flags; 

UBYTE *name,c0,c1 ; 

VOID delay_func(),0penAUO; 

int xin=1,yin=1; 

OpenAUO; 

y=0; /* set up a Hi Res Custom Screen */ 

w=640; 

h=200; 

d=3; 

c0=0x00; 
c 1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,cO,d , mode, NULL) ; 

ShowTi t le(Scrn, FALSE) ; 

name=NULL; /* set up a Window to serve as a backdrop */ 

x=0; 

y=0; 

w=640; 

h=200; 

f lags=ACTIVATE | SMART REFRESH; 

c0=-1 ; 

d=-1; 

wind=(struct Window *) 

make_wi ndow(x,y,w,h, name, f Lags, cO,d ,Scrn, NULL) ; 

/* initialize the Gelslnfo structure */ 

g_init(wind,8vhead,8vtai l,8ginfo) ; 

/* initialize the VSprite structure */ 

vimp.Height=16; 

vimp.Width=16; 

vimp.Depth=2; 

vimp.SprColors=colors; 

vimp. ImageData=vimp_dataO; 

vimp.X=25; 

vimp.Y=25; 

vimp.Flags=VSPRITE; 

AddVSprite(&vimp,wind->RPort); /* add the VSprite to the list 

x=y=25; 

for(i=0;i<1000;i++) { /* move the VSprite around */ 
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Listing 6-8. (cont.) 



if(x < X_LF_BORDER) { /* change direction at the left hand border */ 
x=X_LF_BORDER+1; 
xin=1 ; 

vimp. ImageOata=vimp dataO; 
> 

else if( x > X_RT_BORDER) { 
x=X_RT_BOR0ER-1 ; 
xin=(-1 ) ; 

vimp. ImageOata=vimp datal; 
> 

else 
x+=xin; 

if (y < Y_TP BORDER) { 
y=Y_TP_i0RDER+1 ; 
yin=1; 

vimp. ImageData=vimp dataO; 
} 

else if(y > Y_BT_BORDER) { 
y=Y_BT_B0RDER-1 ; 
yin=(-T); 

vimp. ImageData=vimp datal; 
> 

else 
y+=yin; 

vimp.X=x; 
vimp.Y=y; 

s_di splay(wind,Scrn,Svimp) ; 
} 



CloseWindow(wind) ; 
CloseScreen(Scrn); 

> 



In Listing 6-8, two changes occur to the VSprite object when it reaches a 
boundary; not only is its direction changed but its shape as well. This latter 
change is accomplished by switching the value of the ImageData member 
back and forth between two arrays: 

vimp_dataO{] the ubiquitous happy face 
vimp_data[ ] a rarer mad face. 

Any change can be made to a VSprite, including a new position, a new shape, 
or a new color. The change will become manifest immediately after execution 
of the rendering sequence. Note that in this example, the functions g_init<) 
and s_ display ( ) are used. 

One of the major reasons for using the software based VSprites is the 
freedom we have to create and manipulate many such objects. Listing 6-9 



/♦...and a the right one */ 



/* move down at the top */ 



/* move up at the bottom */ 



» ^ £f X 



I* close down the window */ 
/* and the screen */ 



247 



Animating the Sprites 



illustrates a program that creates and manipulates two virtual sprites. In 
this program, the code that calculates the new position of each virtual sprite 
has been moved to a function' new _move< j\ this will produce a program that 
is more straightforward in design and easier to follow. We declare two differ- 
ent image arrays to create distinctive looking objects. We still have only a 
single Gelslnfo structure and a single GELs list. The vimpO variable is 
initialized and then, since many of the values will be the same, we assign 
vimpl the values from vimpO. It is only necessary to change the SprColors 
member and the ImageData pointer. Two calls to AddVSprite( ), one for each 
object, create our animation list. 

Listing 6-9. Manipulating several VSprites. 



((include <exec/types.h> 
((include <intui t ion/intui tion. h> 
((include <graphi cs/rastport.h> 
((include <graphics/sprite.h> 
((include <graphics/gfxmacros.h> 
((include <graphi cs/gels.h> 
((include <graphics/view.h> 
/(include <exec/memory.h> 



((define Y_BT_B0RDER 183 

((define Y~Tp"bORDER 1 

#define x]rT~B0RDER 605 

((define X LF BORDER 1 



/* set some constants to control the VSprite * 
/* movement — quite arbitrary */ 



struct Screen *Scrn; 
struct Window *wind; 

struct VSprite vimpO, vimpl ,vhead,vtai I; 
struct Gelslnfo ginfo; 

USHORT colors0[]={0x0f00,0x00f0,0x000f>, 
colorsl []=<0x00f0,0x000f ,0x0f00>; 



/* set the VSprite color range * 



UW0RD vimp_dataO[]= < 



vimp_data1 []={ 



/* the image data that defines the VSprite i 
0x07e0,0x07e0, 
0x0810,0x0810, 
0x1008,0x1008, 
0x2004,0x2004, 
0x4c32,0x4c32, 
0x9e79,0x9e79, 
0x8c31 ,0x8c31 , 
0x8001,0x8001, 
0x8001,0x8001, 
0x8001 ,0x8001 , 
0x9009,0x9009, 
0x4812,0x4812, 
0x27e4,0x27e4, 
0x1008,0x1008, 
0x0810,0x0810, 
0x07e0,0x07e0>, 

0x07e0,0x07e0, 



1 
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Listing 6-9. (cont.) 



0x0810,0x0810, 
0x1008,0x1008, 
0x2004,0x2004, 
0x4c32,0x4c32, 
0x9e79,0x9e79, 
0x8c31,0x8c31, 
0x8001,0x8001, 
0x8001 ,0x8001 , 
0x87e1,0x87e1, 
0x8811,0x8811 , 
0x500a, 0x500a, 
0x2004,0x2004, 
0x1008,0x1008, 
0x0810,0x0810, 
0x07e0,0x07e0>; 

mainO 
< 

SHORT x,y,w,h,d,i ; 
USHORT mode; 
UL0NG flags; 
UBYTE *name,c0,d; 
VOID delay_func(),OpenAUO; 
int x0,y0,x1 ,y1 ,xin0,yin0,xin1 ,yin1 ; 

OpenAUO; 

y=0 ; /» set up a Hi Res Custom Screen */ 

w=640; 

h=200; 

d=3; 

c0=0x00; 
c 1=0x01; 
mode=HIRES; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,cO,d , mode, NULL) ; 

ShowTi t leCScrn, FALSE); 

name=NULL; /* set up a Window to serve as a backdrop */ 

x=0; 

y=0; 

w=640; 

h=200; 

f lags=ACTIVATE | SMART_REFRESH ; 

c0=-1 ; 

d=-1; 

wind=(struct Window *) 

make_wi ndow(x,y,w,h, name, f lags, cO,d ,Scrn, NULL); 

/* initialize the Gelslnfo structure */ 



* * ° 
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Listing 6-9. (cont.) 



g_i ni t (wi nd,8vhead,Svtai I ,8gi nfo) ; 

/* initialize the VSprite structures */ 

vimpO.Height=16; 

vimp0.width=16; 

vimpO.Depth=2; 

vimpO. SprColors=colorsO; 

vimpO. ImageData=vimp_dataO; 

vimpO.X=25; 

vimpO.Y=25; 

vimpO.Flags=VSPRITE; 



p OHMAT 
ZERO 

2 A R A GOZ A 



vimp1=vimp0; 

vimpl .SprColors=colors1 ; 
vimpl . ImageData=vi mp_data1 ; 



/* initialize the second VSprite structure */ 
/* customize the second VSprite */ 



/* add the VSprites to the list */ 



AddVSpri te (8vi mpO , wi nd->RPort) ; 
AddVSpri te(8vimp1 ,wind->RPort) ; 

xO=yO=25; 
x1=y1=30; 



for(i=0; i <1000; i++) { /* move the VSprite around */ 

new_move(SxO,SyO,8xinO,SyinO) ; 
vimpO.X=xO; 
vimpO.Y=yO; 

s_di splay (wi nd, Scrn.Svi mpO) ; 

new_move(8x1 ,8y1 ,8x ,n1 ,8yin1) ; 
vimpl .X=x1 ; 
vimpl .Y=y1 ; 

s_di splay(wind,Scrn,8vimp1 ) ; 



CloseWindow(wind) ; 
CloseScreen(Scrn) ; 



/* close down the window */ 
/* and the screen */ 



new_move(x,y,xin,yin) 
int *x,*y,*xin,*yin; 
{ 

if<*x < X_LF_BORDER) { /* change direction at the left hand border */ 
*x=X_LF_BORDER+1 ; 
*xin=1 ; 

} 

else if( *x > X_RT_BORDER) < /*...and a the right one * 

*x=X_RT_BORDER-1; 
*xin=(-T); 

> 

else 

*x+=*xin; 
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Listing 6-9. (cont.) 



if(*y < Y_TP_BORDER) { 
*y=Y_TP_BORDER+1 ; 
*yin=1 ; 

> 

else if <*y > Y_BT_BORDER) { 
*y=Y_BT_BORDiR-1; 
*yin=(-1 ) ; 

> 

else 

* y +=*yin; 

> 



Bobs 

The other basic unit of the GELs system is the blitter object or Bob. The Bob 
is not rendered through the hardware sprite system; instead, it is a part of 
the background display. As a Bob is moved, the display area in its path is 
altered with a new image. These changes are rapid enough that the movement 
appears smooth and steady. The big advantage of the Bob is that there is no 
restriction on the size or width of the object's image. It does, however, take 
more system resources to produce and is in fact, if not in perception, slower 
than the virtual sprite. 

From the programmer's point of view, the big difference between 
VSprites and Bobs is in the way the image is drawn. Since Bobs are not 
restricted to a sixteen pixel width, their image is created through a series of 
overlapping bit planes that specify a pointer to a color register for each pixel; 
Figure 6-11 illustrates this arrangement. This use of bit planes is identical to 
the way Intuition creates images. 

A Bob is created through the use of two associated data objects. 

a variable of type struct Bob 
a VSprite variable. 

These two variables are linked to each other through mutually referencing 
members in each variable: the VSBob member in the VSprite and the 
Bob VSprite member in the Bob variable. The VSprite variable that defines a 
Bob must be initialized in a slightly different way than when it is used as a 
virtual sprite support device. Most importantly, the Flags member must not 
be set to the VSprite flag value, also the SprColors member has no use and 
should not be initialized. ImageData will point at an array of sixteen bit 
words, but this array is arranged in a different way from the VSprite image. 
The Depth and Width members now have significance. Depth is set to indi- 
cate how many bit planes are used to define the Bob object— it can be any- 
thing up to and including the specified depth of the display field. As before, 
Width will contain the number of sixteen bit words necessary to specify the 
width of the image. Remember, this value is the number of words needed to 



/* move down at the top */ 



/* move up at the bottom */ 



251 



Animating the Sprites 



Figure 6-11. Bit planes for the Bob 
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depth bit planes 



— width words long — 



contain all the pixels-if your Bob is, for example, 40 pixels wide you 
need to specify a Width of 3. Depth, Height, and Width define how the 
system will mterpret your image data-each bit plane will be made up 0 
Height rows of Width columns. Depth indicates how many of these planes 
expected. 

There is one additional factor that must be considered when specifying 
Bob image. If the image has a depth that is shallower than the underlaying 
display, it is necessary to specify in which bit planes of the display the bi 
planes of the Bob image are to be rendered. This is illustrated in Figure 6- ' 
The member PlanePick in the VSprite structure is used to set this value! 
Where you place your bit plane can have an effect on the color that is used tJ 
render the Bob image. The display hardware will use all the bitplanes in tnl 
display to find the color for a given pixel. Suppose a Bob of depth 2 is drawn: 
in the first two bit planes of a five bit plane display; this will yield a ver| 
different color register value than if it were drawn in the last two bit plane* 

The GELs system that supports VSprite also controls Bobs. Bobs art 
added to the GELs animation list through a call to the system function. ' 

AddBob(b f r) 

where 6 is a pointer to a Bob variable and r is the address of the displa- 
EastPort. The same rendering and display sequence is used for these as f 
virtual sprites. A call to 
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RemIBob(b, r, vp) 

will remove the object from the animation list. Here 6 is a pointer to the 
specific Bob to be removed, r, to the RastPort, and vp to ViewPort of the 
display environment. 

Figure 6-12. PlanePick 
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Examples Using Bobs 

As with VSprites, Bobs make more sense in context. Since they are GELs 
objects, we can use our support library to change and move these objects. 
Listing 6-10 shows a simple program using a Bob object. Within the context 
of a low resolution screen, we create a boxy shape of three colors and move it 
across the display. Whenever it comes up against a boundary, we change its 
direction— this is the same program we used to illustrate virtual sprites 
before. As the Bob moves, it drags a copy of itself along with it— effectively 
drawing a series of ribbons on the monitor's display. 
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Listing 6-10. A simple Bob program. 



"include <exec/types.h> 
"include <intuition/intuitiqn.h> 
"include <graphi cs/rastport .h> 
"include <graphics/sprite.h> 
"include <graphics/gfxmacros.h> 
"include <graphi cs/gels.h> 
"include <graphics/view.h> 
"include <exec/memory.h> 



"define Y_BT_BORDER 183 
"define Y_TP_B0RDER 1 
"define X_RT~BORDER 285 
"define X_LF BORDER 1 



/* set some constants to control the VSprite */ 
/* movement — quite arbitrary */ 



struct Screen *Scrn; 

struct Window *wind; 

struct VSprite vimp.vhead.vtai I; 

struct Bob bimp; 

struct Gelslnfo ginfo; 



UWORD b_dataC= { 

0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 

Oxffff.Oxffff, 
Oxffff.Oxffff , 
Oxffff.Oxffff , 
Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 

Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 



Oxffff , 
Oxffff, 
Oxffff 
Oxffff, 
Oxffff, 
Oxffff, 



Oxffff, 
Oxffff, 
Oxffff, 
Oxffff, 
Oxffff, 
Oxffff, 



0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 



/* the image data that defines the VSprite */ 
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Listing 6-10. (cont.) 



0x0000,0x0000, 
0x0000,0x0000, 

Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff, 
Oxffff.Oxffff}; 



mainO 



SHORT x.y.w.h.d.i; / 7 

USHORT mode; ^ A n «*T w 

ULONG flags; flT^ 
UBYTE *name,c0,c1; . / 

VOID delay.funcO.OpenAUO; < ' 

int xin=1,yin=1; " 

OpenAUO; 

y=0; /* set up a Custom Screen */ 

w=320; 

h=200; 

d=5; 

c0=0x00; 
d=0x01; 
mode=NULL; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 , mode, NULL); 

ShowTi t leCScrn, FALSE); 

name=NULL; /* set up a Window to serve as a backdrop */ 

x=0; 

y=0; 

w=320; 

h=200; 

f lags=ACTIVATE | SMART REFRESH | BORDERLESS; 

c0=-1 ; 

c1=-1; 

wind=(struct Window *) 

make_wi ndow (x, y.w.h, name, f lags, cO.d .Scrn, NULL); 

/* initialize the Gelslnfo structure */ 

g.init (wind.Svhead.Svtai l.Sginfo); 

/* initialize the VSprite structure */ 

vimp.Height=18; 
vimp.Width=2; 
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Listing 6-10. (cont.) 



vimp.Depth=2; 

vimp. ImageData=b_data; 

vimp.PlanePick=Ox03; 

vimp.X=25; 

vimp.Y=25; 

vimp.Flags=0x0000; 

vimp.VSBob=8bimp; 
bimp.BobVSprite=8vimp; 



2i B 

ZARA 

/* to indicate that we're dealing with a Bob */ 
/* link the Bob and the VSprite structures */ *; 



SetRGB4(8(Scrn->ViewPort) ,29,15,0,0); 
Set RGB4 (8 (Sc rn->Vi ewPort ) .30,15,15,15); 
SetRGB4(8(Scrn->ViewPort) ,31 ,0,0,15) ; 

AddBob(8bimp,wind->RPort); /* add the Bob to the list */ 
x=y=25; 



for(i=0;i<1000;i++) { 
if (x < X_LF_BOR0ER) { 
x=X_LF_B0RDER+1 ; 
x i n=1 ; 
} 

else if( x > X RT BORDER) { 
x=X_RT_B0RDER-1 ;~ 
xin=(-1); 
> 

else 
x+=x l 'n; 

ifCy < Y_TP_BORDER) { 
y=Y_TP_BORDER+1 ; 
yin=1; 
} 

else if(y > Y_BT BORDER) { 
y=Y_BT BORDER-1; 
yin=(-T); 
> 

else 
y+=yin; 

vimp.X=x; 
vimp.Y=y; 

s_display(wind,Scrn,8vimp) ; 
> 

CloseUindow(wind); 
CloseScreen(Scrn) ; 



/* move the Bob around */ 
/* change direction at the left hand border */ 



/*...and at the right one */ j 



/* move down at the top */ 



/* move up at the bottom *J§ 



/* close down the window *| 
/* and the screen */ 
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In this program, we not only declare our necessary three VSprite struc- 
tures but also a variable of type struct Bob. Note that the image data array, b 
_data is more extensive than with the earlier VSprite example. We initialize 
the VSprite structure to values that represent the size and structure of the 
image data 

Height is 18 lines 
Width is 2 words 
Depth is 2 bit planes 

Note that we set the PlanePick member to draw our image in the last two bit 
planes of the underlying display. The Bob variable is set to point at the 
VSprite variable and vice versa and a call to AddBobO creates the animation 
list. Note the calls to SetRGB4() give the program control over the colors that 
will be used to display the object. 

The previous example drew bold images on the display— dragging the 
shape of the Bob across the screen. Often, however, we want an object to move 
without leaving a trace of itself. This too is possible with a Bob but is a more 
difficult operation. We have to save the image of the display, paint the Bob in its 
place and when we move the Bob, replace the old image back on the display 
field. This is accomplished by setting the Flags member of the supporting 
VSprite structure to the SAVE BACK value; in order for this to work, it is 
necessary to specify a buffer at least as big as the Bob image to hold the 
displaced background display. This buffer is assigned to the SaveBuffer member 
of the Bob structure. Listing 6-11 illustrates the operation of this mechanism. It 
is the same program as in Listing 6-10, but we declare an extra image array, 
saved, the same size as b_data/J and assign it to the appropriate member. Of 
course, the initialization includes the use of the SAVEBACK value. 

Listing 6-11. A Bob program illustrating the 
SAVEBACK feature. 



^include <exec/types.h> 

^include <intuition/intuition.h> 

^include <graphics/rastport.h> 

#include <graphics/sprite.h> 

^include <graphics/gf xmacros.h> 

/(include <graphics/gels.h> 

^include <graphics/view.h> 

^include <exec/memory.h> 

#define Y BT BORDER 183 
*/ 

^define Y_TP_BORDER 1 
#define X_RT_B0RDER 285 
#define x'LF^BORDER 1 

struct Screen *Scrn; 
struct Window *wind; 
struct VSprite vimp,vhead,vtai I; 
struct Bob bimp; 



/* set some constants to control the VSprite 
/* movement — quite arbitrary */ 
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Listing 6-11. (cont.) 



struct Gelslnfo ginfo; 

UWORD save[72], 
b_data[]= { 

0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 

Oxffff .Oxffff, 
Oxffff ,0xffff, 
Oxffff .Oxffff , 
Oxffff .Oxffff , 
Oxffff .Oxffff, 
Oxffff .Oxffff, 

Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff .Oxffff , 
Oxffff .Oxffff , 
Oxffff .Oxffff, 
Oxffff .Oxffff , 

Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff. Oxffff, 

0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 

Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff .Oxffff, 
Oxffff , Oxffff); 



/* set aside a buffer for the SAVEBACK faciLity */ 
/* the image data that defines the VSprite */ 




mainO 
< 

SHORT x,y,w,h,d,i; 
USHORT mode; 
ULONG flags; 
UBYTE *name,c0,c1; 
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Listing 6-11. (cont.) 



VOID delay_funcO,OpenAUO; 
int xin=1 ,yin=1 ; 

OpenAUO; 

y=0; /* set up a Custom Screen */ 

w=320; 

h=200; 

d=5; 

c0=0x00; 
c1=0x01 ; 
mode=NULL; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 , mode, NULL) ; 

ShowTi t le (Scrn , FALSE) ; 

name=NULL; /* set up a Window to serve as a backdrop */ 

x=0; 

y=0; 

w=320; 

h=200; 

f lags=ACTIVATE | SMART REFRESH | BORDERLESS; 

c0=-1 ; 

d=-1; 

wind=(struct Window *) 

make_wi ndow(x,y,w,h, name, f Lags, c0,c1 , Scrn, NULL) ; 

/* initialize the Gelslnfo structure */ 

g_i nit (wind, Svhead.Svtai l.Sginfo); 

/* initialize the VSprite structure */ 

vimp.Height=18; 

vimp.Width=2; 

vimp.Depth=2; 

vimp. ImageData=b_data; 

vimp.PlanePick=0x03; 

vimp.X=25; 

vimp.Y=25; 

vimp. F lags=SAVEBACK; /* set the flag to redraw background */ 

vimp.VSBob=8bimp; /* link the Bob and the VSprite structures */ 

bimp.BobVSprite=Svimp; 

bimp.SaveBuf fer=save; /* set up save buffer. */ 

SetRGB4(8(Scrn->ViewPort),29,15,0,0); /* set up the color registers */ 
SetRGB4(8(Scrn->ViewPort) ,30,15,15,15) ; 
SetRGB4(8(Scrn->ViewPort),31,0,0,15); 
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Listing 6-11. (cont.) 



AddBob (Sbi mp ,wi nd->RPort) ; 
x=y=25; 

for<i=0;i<1000;i++) { 
if<X < X LF BORDER) { 
x=X_LF_B0RDER+1 ; 
xin=1 ; 
} 

else if( x > X RT BORDER) { 
x=X_RT_B0RDER-1; 
xin=(-T) ; 
} 

else 
x+=xin; 

if(y < Y_TP_BORDER) < 
y=Y_TP JiORDER+1 ; 
yin=1; 
> 

else if(y > Y_BT_BORDER) <. 
y=Y_BT_B0RDER-1 ; 
yin=(-T) • 
> 

else 
y+=yin; 

vimp.X=x; 
vimp.Y=y; 

s_display(wind,Scrn,Svimp) ; 
} 

CloseWindow(wind); 
CloseScreen(Scrn); 



/* add the Bob to the list */ 



/* move the Bob around */ 

/* change direction at the left hand border */ 



/♦...and at the right one */ 



/* move down at the top */ 



/* move up at the bottom */ 



/* close down the window */| 
/* and the screen */ 



Finally, Listing 6-12 contains a program that will display both a VSprite 
and a Bob simultaneously on the display screen. Both move and change^ 
direction at each specified boundary. Since the same animation list and thai 
same rendering commands support both kinds of objects, they can be freelyf 
mixed in a program. 

Listing 6-12. An example mixing VSprites and Bobs. 



^include <exec/types.h> 
^include <intuition/intuition.h> 
^include <graphics/rastport.h> 
#include <graphics/sprite.h> 
^include <graphics/gfxmacros.h> 
#include <graphics/gels.h> 
^include <graphics/view.h> 
#incLude <exec/memory.h> 
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Listing 6-12. (cont.) 



#define Y_8T_B0RDER 183 
tfdefine Y_TP_B0RDER 1 
#define X_RT_BORDER 285 
#define XLF'bORDER 1 



/* set some constants to control the VSprite */ 
/* movement — quite arbitrary */ 



struct Screen *Scrn; 
struct Window *wind; 

struct VSprite vimp0,vimp1 ,vhead,vtai I; 
struct Bob bimp; 
struct Gelslnfo ginfo; 

USHORT colors0C]={0x0f00,0x00f0,0x000f>; /* set the VSprite color range */ 



UUORD vimp_dataOn= { 
0x07e6,0x07e0, 
0x0810,0x0810, 
0x1008,0x1008, 
0x2004,0x2004, 
0x4c32,0x4c32, 
0x9e79,0x9e79, 
0x8c31,0x8c31, 
0x8001,0x8001 , 
0x8001,0x8001, 
0x8001,0x8001 , 
0x9009,0x9009, 
0x4812,0x4812, 
0x27e4,0x27e4, 
0x1008,0x1008, 
0x0810,0x0810, 
0x07e0,0x07e0}, 
saveC72], 
b_dataH= { 

0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 

Oxffff ,0xffff , 
Oxffff ,0xffff , 
Oxffff , Oxffff , 
Oxffff ,0xffff , 
Oxffff .Oxffff , 
Oxffff .Oxffff, 

Oxffff .Oxffff , 
Oxffff .Oxffff. 
Oxffff .Oxffff, 
Oxffff .Oxffff , 
Oxffff, Oxffff, 
Oxffff .Oxffff , 



/* the image data that defines the VSprite */ 



/* set aside a buffer for the SAVEBACK facility */ 
/* the image data that defines the VSprite */ 
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Listing 6-12. (cont.) 



Oxffff, Oxffff, 
Oxffff .Oxffff, 
Oxffff, Oxffff, 
Oxffff, Oxffff, 
Oxffff, Oxffff, 
Oxffff, Oxffff, 

0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 
0x0000,0x0000, 

Oxffff .Oxffff, 
Oxffff, Oxffff, 
Oxffff, Oxffff, 
Oxffff, Oxffff, 
Oxffff, Oxffff, 
Oxffff .Oxffff}; 



ua i n ( ) 
< 

SHORT x,y,w,h,d,i; 

USHORT mode; 

ULONG flags; 

JBYTE *name,cO,d; 

TOID delay_funcO,0penAll(); 

int X0,y0,x1,y1,xin0,yin0,xin1,yin1; 

JpenAUO; 

, T ~3^ 0 . '* set up a Custom Screen */ 

»=200,' 
d=3; 

<0=0x00; 
d=0x01; 
node=NULL; 

Scrn=(struct Screen *) 

make_screen(y,w,h,d,c0,c1 .mode, NULL) ; 

ShowTi t Le(Scrn, FALSE) ; 

name=NULL; /. set up , win dow to serve as a backdrop */ 

y=0; 

w=320; 

h=200; 

f lags=ACTI VATE | SMART REFRESH | BORDERLESS; 
c0=-1; 
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Listing 6-12. (cont.) 



d=-1; 

wind=(struct Window *) 

make_wi ndow(x, y.w.h, name, f Lags, cO.d.Scrn, NULL); 

/* initialize the Gelslnfo structure */ 

g.init Cwind.Svhead.Svtai l.Sginfo); 

/* initialize the VSprite structures */ • 



vimpO.Height=16; u 
vimpO.Uidth=16; W |^ T3 [J 

vimp0.0epth=2; *• / 

vimpO.SprColors=colorsO; 2ABAftA7 A 

vimpO.ImageData=viinp dataO; » « * « « U * " 

vimpO.X=25; 
vimpO.Y=25; 
vimpO.Flags=VSPRITE; 

/* initialize the second VSprite structure to support a Bob */ 

vimpl .Height=18; 

vimpl. Width=2; 

vimpl .Depth=2; 

vimpl .ImageData=b_data; 

vimpl .PlanePick=0x03; 

vimpl .X=30; 

vimpl .Y=30; 

vimp1.Flags=SAVEBACK; /* set the flag to redraw background */ 

vimpl. VSBob=8bimp; /* n n k the Bob and the VSprite structures */ 

bimp.BobVSprite=8vimp1 ; 

bimp.SaveBuffer=save; /* set up save buffer . „ 

SetRGB4<8(Scrn->ViewPort),29.15,0,0>; /* set up the color registers */ 

SetRGB4(8(Scrn->ViewPort),30,15,15,15); 

SetRGB4(8(Scrn->ViewPort),31 ,0,0,15); 

AddBob(8bimp,wind->RPort); /* add tne Bob t0 the tlst „, 

AddVSprite(8vimp0,wind->RPort); /* add the VSprites to the list */ 

xO=yO=25; 
x1=y1=30; 

for(i=0;i<1000;i++) { /* move the VSprite around */ 

new_move(8x0,8y0,8xin0,8yin0); 
vimp0.X=x0; 
vimpO.Y=y0; 

s_di splay (wind, Scrn.SvimpO) ; 
new_move(8x1,8y1,8xin1,8yin1); 
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Listing 6-12. (cont.) 



vi'mpl .X=x1 ; 
vimpi .Y=y1 ; 

s_di splay (wind, Scrn,8vimp1), • 

CloseWindowCwind); close down 

^CloseScreenCScrn); „ and tJ|- screen #/ 

new_move<x,y,xin,yin) 
int *x,*y,*xin,*yin; 

'S^ifcXi? 0 { '* Chan9B d1rectlon at th * ^ft hand border ./ 
*xin=1; 

?0^y 0 *°™ 1 « th « -«*« one 

else 
*x+=*xin; 



TT-C 

^.^iSasfr" { z ^ * * G °*™ do - « - e «* - 

*yin=1; 

*yin=(-T); 
> 

else 
*y+=*yin; 

3 



Summary 



la this short chapter, we have explored programming with the sprites, hardwarl 
controlled objects that can coexist in the display area with windows, screen^ 
aad other graphic objects. The sprites are independent of any enclosing stru<| 
ture and can move freely The mouse cursor is a sprite-sprite 0, to be specific! 

Controlling these useful objects is easy through a software support system! 
of ered by the Amiga. You can access the hardware parameters through i ' 
SimpleSprite structure and define its shape with an array of 16-bit worus 
Manipulation of sprites is facilitated by a series of system functions that alien* 
ycu to initialize, change, and move them. Manipulation of VSprites and Bobs W 
similarly accomplished by the software environment. 

We have also explored the GELs subsystem and its VSprites and BobS 
building blocks. 
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he Amiga has the capability to produce high quality, stereophonic 
•JL. sound. Four independent audio channels in the hardware support a 
flexible and easily programmed subsystem. The audio channels are general- 
purpose, digital-to-analog converters rather than specialized music producing 
chips. This allows a wide variety of sounds, from special effects to rich and 
complex musical notes. 

In this chapter, we will explore the important features of this subsys- 
tem. Multiple channels will be used to produce both monaural and stereo- 
phonic sound. Each example will treat, as much as possible, a single aspect of 
this important resource. 

Creating Sounds 

Sound is composed of compression waves in a physical medium, usually air. 
The source— a musical instrument, stereo speaker, etc.— produces com- 
presssions and rarefactions of the air. These are received by our ears and 
translated into sounds (Figure 7-1). Two important points should be noted: 

1. Sound is defined by a series of parameters. 

2. The perception of sound is largely determined by a psychological 
component. 

The scope of this chapter does not allow us to do much more than mention 
these important aspects of sound, but we must always keep them in mind as 
we start to experiment with sound generation. The psychological component 
of sound is especially difficult to pinpoint, even in a single occurrence. Con- 
sider the distinction between pleasant and unpleasant sounds. One persons 
music is another's noise. Even a particular sound takes its coloration from the 
circumstances: the raucous clang of the city may be pleasant after a long 
sojourn in the country, or unpleasant and distracting under different circum- 
stances. More practically, certain sounds can affect their mutual perception, 
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producing something more than the mere sum of their parts The Amieas 
extensxve sound subsystem makes this kind of experimentation easy aTL 

Figure 7-1. Sound is transmitted via a compression wave in air 
and then interpreted by the human ear 




We nld S2T^^ SOUnd 0f more ^mediate interest to us. 
We need to understand which aspects of a sound wave vary to produce 
perceptible differences to our ears. Unfortunately, there are a great mZ 
parameters that affect sound, such as the temperature oTthe S Ld 5e 
acoustic properties of the space in which we are hearing the sound Holever 
sound" 6 Pr ° PertieS WhiCh repreSent the *y t0 Producing Iny 

1. The frequency of the wave 

2. The amplitude of the wave 

3. The tone quality or timbre 

Zc^trthT^ 3 W ° rkiDg dGfiniti0n ° f th6Se qUahtieS bef0re P roc ^ 
The frequency of a sound wave is the basic parameter; waves of differefl 
frequency are perceived as different tones. Middle C on the piano for exaS 

ta'iSrVEl CydeS ^ r° nd By this Parame^ we cr P - ; 

duce notes of different tone. Complex sounds-such as noise-are made up ol 

somTof'th ° many ° f SUCh ^ t0nCS - Fi ^ Ure 7 " 2 Usts frequ^ncLsd 
some of the most common musical tones. : 

The amplitude of a sound is another attribute whose effect is obvious! 
this presents the loudness of a sound. Varying this attribute makes J3 

louH on r /h SS /r ; g ° mg u t0 qUi6t ° n ° De end 0f the s P ectr ™ and pain 
££S t \ LeSS ° b ! 10US iS the faCt that this > t0 °- is a component in 
ETS?ff c 7Plex sounds. A mixture of different frequencies where ea^ 
has a different amplitude, sounds different than a mixture where each of 
tones is at the same level of loudness. 

The most difficult parameter to explain is timbre. This can be loo" 
described as the "quality of sound." The frequency dictates what lone 
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Figure 7-2. Approximate frequencies of selected common 
musical notes 
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being created, but the same tone can be perceived in a variety of different 
ways. An example can be taken from the musical scale. An "A" note sounded 
on a violin and the very same note on a piano are recognizably the same note, 
but each also has a perceptibly different quality. You are not likely to mistake 
one for the other. There are a number of factors involved in defining this 
quality; a complete discussion is beyond the scope of this chapter. The timbre 
is a kind of general purpose parameter which allows us to get a handle on the 
complexity of a sound. 



Computerized Sounds 

With this general picture of the factors that go to make up a sound, we must 
turn our attention to the techniques for creating sounds on the Amiga. You 
have seen that sound is a recurring object, which may be described mathemat- 
ically; this is also the way to approach sound creation from the computer side. 
You simulate the sound mathematically and then depend on the Amiga's 
circuitry to reproduce this simulation through the speakers. 

The big problem in creating sound on the Amiga or any other computer 
is one of translation between the analog physical world and the internal 
digital representations used by the computer. This basic dichotomy— digital 
vs. analog— is illustrated in Figure 7-3. Analog quantities, such as sound, are 
continuous, one value merging into the next with nothing in between. Digital 
values, in contrast, are discrete: there is a definite transition between two 
adjacent values. 

How can you represent a continuous value in terms of a discrete repre- 
sentation? The solution to this problem is a technique known as sampling 
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Figure 7-3. A continuous function compared to an 
incremental one 




(Figure 7-4). A continuous quantity, such as a sound, exists over a certain 
time period. In the case of a sound, this time period represents one portion, or 
cycle, of a recurring quantity. During one of these intervals, you can note, or 
sample, the value present at various points in the interval. Each time yo 
take a sample, you convert it to a number. This collection of numbers repre- 
sents a discrete description of the quantity at a particular moment. A collec-; 
tion of numbers is easy for a computer to store and manipulate. 



Figure 7-4. Sampling an analog Waveform 




Once this conversion from continuous values to a collection of numbers 
is complete, you are free to manipulate the numbers just as you would any 
numeric quantity in the computer. This kind of representation gives a gregl 
deal of flexibility, for not only dealing with well-behaved sounds— suchjj 
musical notes— but also for creating interesting combinations of sounds, e ~ 
some that never existed in nature. This is where the power of the Amiga 
sound subsystem becomes obvious. 
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Creating Sound on the Amiga 

The specific capabilities of the Amiga to produce sound set it apart from 
most computers with a sound component. First of all, the Amiga produces 
stereo sound. Notice that on the back of the system box are both a left and a 
right speaker output plug; this is an unusual capability for a computer in the 
Amiga's price range. Each stereo channel consists of two virtual channels- 
these are independent sound producing circuits. It is also possible to combine 
• these four virtual channels into a single speaker to produce a monaural sound 
with four components. 

The fact that you are dealing with straight digital-to-analog converters 
and not a specialized sound chip also increases flexibility. Not only can you 
produce virtually any known sound within the machine's freqency range, but 
you can also create brand new sounds. This straight conversion also allows 
more accurate reproduction of musical tones. The Amiga can produce rich 
and pleasing notes that have none of the "computer sound" found in so many 
other microcomputers. 

Access to the sound circuitry is through the audio device. This is pri- 
marily a software object that interfaces with the hardware components of the 
sound subsystem. Like the other driver software found on the Amiga, it runs 
m the multitasking environment, concurrently with any calling software. The 
audio device simplifies access to the hardware parameters. 

Communication between a user application and the audio device is 
through the message system. This device has its own specialized message 
node that is transmitted through one of the I/O system calls; the primary 
ones involved here are BeginlOf), WaitlOf), and ChecklOf). SendlOO and 
DoIOO are rarely used because they interfere with some of the initialized 
fields in the audio device message node-they "de-initialize" the io_Flass 
field of the node. 

Messages are sent: 

• To initialize the sound device 

• To start up a sound 

• To alter the parameters of a sound 

• To terminate a sound 

In addition to I/O messages, the OpenDeviceO and CloseDevicef ) system 
functions are used to attach or remove the audio device to a program. 

The message structure type for the audio device has the following form: 
Struct IOAudio { 

struct IORequest ioa_Request; 
WORD ioa AllocKey; 
UBYTE *ioa Data; 
ULONG ioa Length; 
UWORD ioa_Period, 
ioa_Volume, 
ioa_Cyc les; 
struct Message ioa_WriteMsg; 

>; 



Programming Sound 



You can see the usual message structure bracketing the device-specific infor- 
mation fields, and you can also see that the important sound parameters each 
have a dedicated field in the structure. This structure definition is found in 
devices/audio, h. 

Many of these fields require lengthy discussion in order to understand 
them fully. For now, we will briefly describe each one, so that we can begin a 
more complete discussion with the entire picture in mind. In the IORequest 
structure, the following fields will be important to our use of the audio device: 

ioa_Request.io_Unit indicates which of the four possible channels is 
being addressed. 

ioa_Request.io_Command indicates which operation the audio device, 
is to perform. 

ioa_Request.io_ Flags indicates specific modifications to the 
commands issued to the device. 

There are a number of options available for each one of these fields. 

The next field, ioa^AllocKey, is a unique identifier returned by the 
device after successful allocation of one or more audio channels. This value 
helps tie together channels that have been allocated together. Prior allocation 
of the sound channels makes audio access consistent with a multitasking 
environment, since there is no chance that two tasks will try to simulta- 
neously access the device. You can, however, directly call the device and have 
it sound immediately, without worrying about conflicts with other programs 
or tasks. In this latter case the iotz —AllocKey field is ignored. 

The ioa_Data field serves two functions. When the audio device is 
initially being opened, this field holds a map of the proposed channel alloca- 
tions—which are to be opened and which are not. In subsequent messages, its 
is a pointer to the representation of the waveform' that is to be sounded. Th<§ 
ioa_Length field contains the size of the ioa^Data field. 

The frequency of a sound is specified, not in the familiar units of cycleS 
per second, but as its inverse, the period. There is an easy mathematical" 
relationship between the two: the period is the reciprocal of the frequence 
This value is set in ioa_Period. The loudness is set in ioa_ Volume; and torn 
Cycles tells the device how many times to repeat the sound— how many cyclel 
to actually play. 



Sound Data Representation 

The first area to explore is the actual representation of the sound values B 
the machine. We noted earlier that sampling is the technique for generating 
numeric representation of a continuous sound wave. A sample of a particul 
waveform is a series of values taken across time; that is to say, you measure! 
the waveform at regular intervals and note its actual value. In the case of thflB 
Amiga, you measure the amplitude (loudness). This set of values can be seng 
to the sound subsystem, which reproduces the original sound by converting 
these numbers back into a series of varying voltages. These voltages, in turjH 
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drive the speakers. The frequency of the sound is set by specifying the 
sampling interval. 

It is possible to actually sample sounds with the Amiga and some special- 
ized out-board circuitry; however, because the intermediate step in the "equa- 
tion" is an array of numbers, you can create your own sounds mathematically, 
simply by specifying these numbers. A very convenient way to do this is to fill 
the array using the sin<) function. The resulting sine curve produces a pleas- 
ingly pure tone. You can just as easily initialize the values arbitrarily. There is 
a restriction on the range of values for this data: —127 to 127. 

More realistic sounds can be generated using more complex waveforms. 
Figure 7-5 illustrates some other commonly used shapes, such as the saw- 
tooth waveform. To create arbitrarily complex sounds, combinations of 
waveforms are used. The sample size need not be very large. Even as few as 
two values will yield some kind of sound. There is also no set sample size; the 
ioa._Len.gth field tells the audio device how many values to expect. 

Figure 7-5. Waveforms used to represent sound data 
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Sawtooth Waveform 




Triangular Waveform 



Square Waveform 



The frequency of a tone is set by placing a value into the period field of 
the IOAudio structure— ioa_Period. The period is the inverse of the fre- 
quency and actually specifies the time interval needed for a sample. The time 
unit is clock ticks, the lowest measurable interval on the computer. The 
mathematical relationship between the desired frequency and the period spec- 
ified is calculated by the formula: 

period=(microseconds per sample) -5- 0.279. 

The number of microseconds per sample is a function of the number of items 
in the data, and the desired frequency. For example, if you have a data set 
with thirty-two items and you want a frequency of 5000 Hz, then each cycle is 
1/5000 second. With thirty-two samples per cycle, each sampling interval is 
approximately six microseconds. The period for this frequency is approxi- 
mately 23. Figure 7-6 contains the period values for some musical notes. It 
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should be noted here that the higher the period value, the lower the frequency 
of the sound. 

Figure 7-6. Period values for some common musical notes 
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Accessing the Audio Device 

The audio device is one of many such devices on the Amiga. As such, it }M 
shared resource and its usage must be allocated among the tasks and jr 
cesses that need to use it. A user application must indicate to the operatin- 
system that it needs to use this device. This is accomplished by 
OpenDevicef) function. You have seen this function before in dealing 
other system devices and device drivers; therefore, a lengthy discussion is 
necessary. Here we will concentrate on those operations and specificatic 
that are unique to the audio device. 

The general form of a call to open the audio device takes the form: JP 

Open Devi ce(AUDI0NAME , 0L, audi o_st rue t ,0D 

where 

AUDIONAME is a global constant designating the official name o\, 
the device. 

audio_struct is an object of type struct IOAudio, set up to initiali| 
the device. 
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The global value AUDIONAME is used to protect the programmer against 
future changes in the operating system environment. Right now, if you were 
to look in audio.h, you would find that this has the assigned value "au- 
dio.device"; but there is no guarantee against future operating system revi- 
sions. Most of our attention then will focus on the structure and how it must 
be set up to open the device properly. 

The first thing to do with the audio structure is to attach a reply port so 
that you can receive return messages from the operating device. This is done 
by a simple call to the system function CreatePortf ). Once you have set up 
the reply mechanism, only three fields need to be initialized to open the device: 

ioa_Request.io_Message.mn_Node.ln_Pri to set the priority of your 
proposed access 

ioa_Data to indicate which of the four audio channels is to be opened 
ioa_Length to show the size of the data field 

The first of these fields sets the priority of the request within the multitask- 
ing environment; it should be set to a value consistent with the importance of 
the application. What this value should be is specific to the type of program 
and the circumstances of the operating environment. We use the value 10 for 
most of the examples in this chapter. 

The ioa_Data field must contain a bit map indicating the channels 
which are to be opened by the succeeding function call. Each unit of the audio 
device is assigned one of the bits in this map. To indicate an open channel, its 
corresponding bit is set to 1. A 0 bit indicates an unused channel. Figure 7-7 
indicates the relationship of bits to units. 

Figure 7-7. The relationship of bits and channels in ioa_Data 
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Channel 1 
Channel 2 
Channel 3 

The code fragment: 

sound. ioa_Request.io_Message.mn Node. In Pri=10- 
sound. ioa_Data=8sunit; 
sound. ioa_Length=(ULONG) si zeof (sunit); 

if ((0penDevice(AUDI0NAME,)oL,Ssound,0U) !=NULL exit (FALSE) 

contains the statements necessary for opening the audio device. Sound is a 
previously declared IOAudio structure and sunit is a UBYTE variable initial- 
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ized to OxOf. Notice that we use the address-of operator with sunit to assign it 
to ioa_Data. Remember, this field is doing double duty; usually it contains a 
pointer to the sound data. It is necessary to respect its pointer data type by 
sending it the address of the bit map and not merely the value. Notice, too, 
that ioa_Length is set by using the sizeof operator rather than by trying to 
figure out the correct size of the data and then initializing this field with a 
number. The OpenDevicef ) command expects the name of the audio device 
and a pointer to this newly initialized structure. The function's flag and 
unitNumber parameters are not used and are set to 0; these values are set 1 
corresponding fields in the IOAudio structure. OpenDevice returns a '. 
if the device cannot be opened. 



Audio Device Commands 

Like the other devices on the Amiga, the audio device supports a full range q|| 
commands. Among the most important of these are: 

CMD_ WRITE. This sends a message to the device to start a sound 
on a channel or unit. 

ADCMD_FINISH. This message stops a sound. 
ADCMD_PERVOL. This command alters the volume or period of an j 
executing sound. 

These commands are set in the io —Command field of the ioa_Request field 
within the audio structure. These are not the full range of available coi 
mands, but they are the ones that are used most frequently in sound pn|j 
gramming. 

In addition to the ioa_Requestio —Command field in the IOAudio stnT 
ture, there is also an io —Flags field. Values placed in this latter field allow 
to modify the basic command to fit a variety of circumstances. For exam 
IOF_ QUICK instructs the system to give priority to your request and 
bypass some of the multitasking overhead. Among the possibilities for 
field beside IOF_QUICK are: 

AD IOF _ S YNCC YCLE . This delays execution of the command until] 
the end of the current cycle. 

ADIOF_PERVOL. This loads the values for the period and the 
volume set in the IOAudio structure. 

One or more of these flags is used with each specific command message. J 
In the simplest case, a single channel is accessed to play a sound foiH 
set period of time. This situation is illustrated in Listing 7-1. Notice that 
have incorporated our earlier fragment of code that opened the audio dev fij l 
and have added the necessary declarations. A simple "for" loop creates Jp 
waveform, a sawtooth (Figure 7-8); this information is stored in the 
sound— data/ ]. 
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Listing 7-1. The simplest use of the audio device. The cycle 
field is set to specify the number of cycles. 



^include <exec/types.h> 
#include <exec/memory.h> 
^include <hardware/custom.h> 
#include <hardware/dmabits.h> 
^include <libraries/dos.h> 
#include <devices/audio.h> 

extern struct MsgPort *CreatePort () ; 
struct IOAudio sound; 

UBYTE suni't=0x0f , sound_data [1 28] ; 

mainO 
{ 

UBYTE i; 

if ((sound. ioa_Request. io_Message.mn ReplyPort=CreatePort("p3" 0))==NULL) 
ex i t (FALSE) ; 



sound. ioa_Request. io_Message.mn_Node. ln_Pri=10; 

sound. ioa_Data=&sunit; 

sound . i oa_Length=(UL0NG) si zeof Csuni t) ; 

if ((OpenDevice(AUDI0NAME,0L,8sound,0L)) i=NULL) < 
printf ("Can't open Audio Devi ce\n") ; 
exit (FALSE); 

> 



°sound'da^[i]=i; FOR MAT 

sound_dataC127]=0; 



R O 



sound. ioa_Request.io_Command=CMD_WRITE; Z ARAGOZ A 

sound. ioa_Request. io_Flags=ADI0F_PERV0L| I0F_QUICK; 

sound. ioa_Oata=sound_data; 

sound. ioa_Cyc les=100; 

sound. ioa_Length=si zeof (sound_dat a); 

sound. ioa_Period=508; 

sound. ioa_Volume=64; 



BeginlO(Ssound); 
WaitlO(Ssound); 

CloseOevice(Ssound) ; 

} 
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Figure 7-8. Sawtooth waveform used to represent sound data 
in Listing 7-1 



127 




The final step requires an initialization of the IOAudio structure so 
and the call to the I/O subsystem. Besides setting the CMD_ WRITE co 
mand, we have to set the ADIOF_PERVOL flag to ensure that our so 
data gets transmitted and used by the audio device. IOF_ QUICK ins 
that our request will be transmitted and acted on immediately. The ioa_Da 
field is given the address of the sound^data array, and its length is assign- 
to ioa_Length. We have set the ioa_Period field to 508. middle C on 
piano, and toa_ Volume to 64, the highest setting. We have a new field ( 
played here, ioa -Cycles; this sets the number of times the sampling opera" 
will be repeated and the sound produced. We set this value to 100, 
short time. If we set this field to 0, the sound will continue until an exp 
stop command is issued. 

Once we have the desired values in an IOAudio structure, we send 
the device with a call to BeginlOO. WaitlOO puts our program to sleep 
the device is finished and returns our io message structure. A C" 
CloseDevice is prudent, since in a multitasking environment, a device 
may not be unloaded at the time a program is finished. In fact, it cannn 
unloaded, unless all open requests have been balanced by a correspon 
CloseDevicef ) call. 



Controlling the Audio Device 

In our first example, we set up the audio device, specified a tone 
duration, and started the sound. A more realistic sound generating pro 
needs to exercise more control over this device. The first measure of con 
the ability to start a sound and stop it explicitly, rather than speci 
duration through the ioa_Cycles field. The ACDMP_FINISH comm 
places the CMD_ Write in the io -Command field to stop an executing 
Listing 7-2 shows a simple program that implements this finish coi 

The interesting design feature of this program is the creation 
IOAudio structures, sound and finish, attached to the audio devj 
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Listing 7-2. Simple use of the audio device, sending an explicit 
finish command to stop the tone. 



nclude <exec/types.h> 
nclude <exec/memory.h> 
nclude <hardware/custom.h> 
nclude <hardware/dmabits.h> 
nclude <libraries/dos.h> 
nclude <devices/audio.h> 
nclude <lattice/stdio.h> 



#include <lattice/math.h> 

extern struct MsgPort *CreatePort O ; 
struct IOAudio f ini sh, sound; 

UBYTE sound_dataC32],sunit=0x0f; 

mainO 

{ 

if ((sound. ioa_Request.io Message. mn ReplyPort=CreatePort("p3",0))==NULL) 
exit (FALSE) ; 

if ((finish. ioa_Request . io_Message.mn ReplyPort=CreatePort ("p2",0))==NULL) 
exi t ( FALSE) ; 

sound. ioa_Request . io_Message.mn_Node. ln_Pri=10; 

sound. ioa_Data=8sunit; 

sound. i oa_Length=(ULONG) si zeof (sunit) ; 



E,QL,Ssound,OL))i=NULL) f > Tr?» _ 
io DeviceW); ^RltfAT 

z H o 

/* ===Set up the command structures=== */ ^RAQQ2^ 



i f ( (OpenDevi ce(AU0IONAME 
printf ("Can't open Aud 
exit (FALSE); 

> 



f inish=sound; 

finish. ioa_Request . io_Flags=IOF_QUICK; 
finish.ioa_Request.io_Command=ADCMD_FINISH; 

/*===============Finished with the initialization= 

f i I l_data(sound_data) ; 



sound, 
sound, 
sound, 
sound, 
sound, 
sound, 
sound . i oa_Vo lume=1 0 ; 

BeginlO(Ssound); 



oa_Request . io_Command=CMD_WRITE; 
oa_Request.io_Flags=ADIOF_PERVOL| I0F_QUICK; 
oa_Data=sound_data; 
oa_Cycles=0; 

oa_Length=si zeof (sound_data) ; 
oa_Period=508; 
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Listing 7-2. (cont.) 



deLayCIOOOOO); 

BeginlO(Sfinish); 
UaitlO(Ssound); 

C LoseDevi ce(Ssound) ; 



f i U_data(sound) 
UBYTi *sound; 
{ 

double x; 

for(x=-(PI/2);x<=PI/2;x+=.1) 

*sound=(UBYTE)f loor(100*si n(x) ) ; 



zA RAGOZ A 



delay(x) 
Long x; 
{ 

Long i ; 

for(i=0;i<x;i**) 



sound structure is used to initialize and start up thfr note. The finish strtt 
ture, in contrast, is reserved for device control. We set up an audio strucjr 
and open the device. Once this has been successfully completed we copy? 
now initialized fields over to the remaining structure. At this point, we 
two structures that are keyed to both the audio device and the same sp 
channel. Once this is done, we initialize first the sound structure to produajj 
the tone and the finish structure to end it. This latter is accomplished? 
setting the io -Command field. We then call BeginlOO, passing it the so 
structure; but instead of pausing our program and waiting for this cornm. 
to run its course, after a suitable delay, we again call BeginlOO. This timf 
pass it the finish structure and then do a WaitlOf ). 

For the sake of simplicity, our delay function is primitive— just a 
loop. However, this program illustrates a general form that can be usi 
larger and more complex applications. A sound generating program does 
have to go to sleep after creating a note, but can do other things— perhapf 
up the next note— while the audio device is processing its request. -|| 

This example program uses a generated sine curve to produce 
pleasing tone. The sine is easily computed and is a well-behaved mathem|L 
object. Listings 7-3 and 7-4 are identical to our current example except ag 
waveform data; the first uses a square wave and the latter, a triangul 
(Figure 7-9). These three programs serve to illustrate the difference^ 
duced by using different waveform data. 
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Listing 7-3. Simple use of the audio device with a square wave. 



^include <exec/types.h> 

#incLude <exec/memory.h> 

#incLude <hardware/custom. h> 

tfincLude <hardware/dmabi ts . h> 

#incLude <Libraries/dos.h> 

flincLude <devi ces/audio.h> 

#incLude <Latti ce/stdio.h> 

SincLude <lattice/math.h> 

extern struct MsgPort *CreatePort () ; 
struct IOAudio f i ni sh, sound; 



UBYTE sound_data [32] , suni t=0x0f ; 

mainO 

{ 



i f ((sound. ioa_Request . io_Message.mn_ReplyPort=CreatePort ("p3",0) )==NULL) 
exi t (FALSE) ; 

if ((finish. ioa_Request . io_Message.mn_ReplyPort=CreatePort ("p2",0))==NULL) 
exi t (FALSE) ; 

sound. ioa_Request . i o_Message . mn_Node . ln_Pri=10; 

sound . i oa_Data=Ssuni t ; 

sound. ioa_Length= (ULONG) si zeof (suni t) ; 

if ((0penDevice(AUDI0NAME,0L,8sound,0L)) i=NULL) { 
printf ("Can't open Audio DeviceVn"); 
exi t (FALSE) ; 

} 

/* ===Set up the command structures=== */ 
f inish=sound; 

finish. ioa_Request . io_F Lags=IOF_QUICK; 
finish. ioa_Request. io_Coramand=ADCMD_FINISH; 

/*===============Fi ni shed with the i ni t i a I i zat i on======*/ 

f i L L_data(sound_data) ; 



sound. ioa_Request . io_Command=CMD_WRITE; 

sound. ioa_Request . io_F Lags=ADIOF_PERVOL | IOF_QUICK; 

sound. ioa_Oata=sound_data; 

sound. ioa_Cyc Les=0; 

sound. i oa_Length=si zeof (sound^data) ; 

sound. ioa_Period=508; 

sound. ioa_VoLume=1 0; 

BeginlO(Ssound) ; 



de Lay (100000); 
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Listing 7-3. (cont.) 



BeginlCK&finish); 
WaitlO(Ssound) ; 

CloseDeviceUsound); 

> 

fi U_data (sound) 
UBYTi *sound; 

int x; 

*sound=0; 

sound++; 
for(x=1;x<31;x++) i 

*sound= ( x <1 6) ?1 00 : -1 00 ; 

sound++; 

> 

*sound=0; 



delay(x) 
Long x; 
{ 

long i ; 

for(i=0;i<x;i++) 

# 

} 



Listing 7-4. Simple use of the audio device 
with a triangular wave. 



^include <exec/types.h> 
flinclude <exec/memory.h> 
^include <hardware/custom. h> 
Sinclude <hardware/dmabi ts . h> 
#include <libraries/dos.h> 
^include <devi ces/audio. h> 
^include <lattice/stdio.h> 
#include <Lattice/math.h> 



extern struct MsgPort *CreatePort () ; 
struct IOAudio finish, sound; 

UBYTE sound_data[32] ,suni t=0x0f ; 
mainO 
{ 

if ((sound. ioa_Request.io_Message.mn_ReplyPort=CreatePort("p3",0)) = 
exi t (FALSE) ; 

if((finish.ioa.Request.io_Message.mn.ReplyPort=CreatePort("p2 ,, .0))J. 
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Listing 7-4. (cont.) 



exi t (FALSE) ; 

sound. ioa_Request . io_Message.mn_Node. ln_Pri=10; 

sound. ioa_Data=8sunit; 

sound . i oa_Length= (U LONG) si zeof(sunit); 

if ((0pen0evice(AUDI0NAME,0L,Ssound,0D) !=NULL) { 
printf ("Can't open Audio DeviceW); 
exit (FALSE); 

> 

/* ===Set up the command structures=== */ 
f inish=sound; 

finish.ioa_Request.io_F lags=IOF_QUICK; 

f i ni sh. ioa_Request . io_Command=ADCMD_FINISH; 

/*===============Finished with the initialization======*/ 

f i U_data(sound_data); 

sound. ioa_Request. io_Command=CMD_WRITE; 
sound. ioa_Request. io_Flags=ADIOF_PERVOL| IOF_0.UICK; 
sound. ioa_Data=sound_data; 
sound. ioa_Cyc les=0; 
sound. ioa_Length=sizeof (sound_data) ; 
sound. ioa_Period=508; 
sound. ioa_Volume=1 0; 

BeginlO(Ssound); 

delay(100000); 

BeginlO(Sfinish); 
WaitlO(Ssound); 

C loseDevi ce (Ssound) ; 

> 

f i U_data (sound) 
UBYTi *sound; 
{ 

int x; 

for(x=0;x<=100;x+=20) { 
*sound=x; 
sound++; 

} 

for(x=80;x>=0;x-=20) { 
*sound=x; 
sound++; 

> 

for(x=1;x<=100;x+=20) { 



FORMAT 
ZERO 

2 A RAGOZ A 
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Listing 7-4. (cont.) 



*sound=-x; 
sound++; 

> 

for(x=80;x>=0;x-=20) < 
*sound=(x!=0)?-x:0; 
sound++; 

> 



deLay(x) 
long x; 
{ 

tong i ; 

for(i=0;i<x;i++) 



Figure 7-9. Waveforms for Listings 7-3 and 7-4 
100 80 



-100 



0 




Sound data for PL7-3 



Sound data 
for PL7-4 



In the previous examples, we specify all of the audio channels in 
IOAudio structure that was used to open the audio device. Whenev 
specify a command, it is executed on the first available of the four ch? 
It is also desirable, however, to be able to use a single specific cha 
Listing 7-5 illustrates one technique for accomplishing this goal. The bit ] 
sunit, is initialized to 0x01; this sets the bit assigned to channel 0 in the au J 
device. The device is opened with only this channel active. The risk is 
that channel is in use and a process with a higher priority wants that p 
lar channel, the call to OpenDevicel ) will fail. We will have more to say 
this topic when we turn our attention to multichannel usage. 

Listing 7-5. Use of a single channel of the audio device. 

/(include <exec/types.h> 

/(include <exec/memory.h> 

//include <hardware/custom.h> 

/(include <hardware/dmabits.h> 

/(include <libraries/dos.h> 

/(include <devices/audio.h> 
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/(include <lattice/stdio.h> 
/(include <Lattice/math.h> 

extern struct MsgPort *CreatePort () ; 
struct IOAudio cont rol, fini sh, sound; 

UBYTE sound_data [32] , suni t=0x01 ; 

ma i n ( ) 

{ 

int i ; 
long d; 

UWORD period=1000, loudness=64; 

if ((control. ioa_Request.io_Message.mn ReplyPort=CreatePort ( M p1 ",0) )==NULL) 
exi t ( FALSE) ; 

if ((finish. ioa_Request. io Message. mn ReplyPort=CreatePort ("p2",0) )==NULL) 
ex it (FALSE) ; 

if ((sound. ioa_Request.io_Message.mn ReplyPort=CreatePort ( M p3",0) )==NULL) 
ex i t ( FALSE) ; 



control . ioa_Request . io_Message.mn_Node. ln_Pri=10; 

control . ioa_Data=&suni t ; 

control. ioa_Length= (UL0NG) si zeof ( sunit) ; 

if ((OpenDevice(AUDIONAME,0L,8control,0D) i=NULL) { 
printf ("Can't open Audio DeviceW); 
exit (FALSE); 

> 

FORMAT 
ZERO 

finish. ioa_Request.io_Flags=IOF_QUICK; Z A R A G O Z A 

f i ni sh . i oa_Request . i o_Command=ADCHD_F IN ISH ; 

control. ioa_Request . io_Flags=I0F_QUI de- 
control. ioa_Request . i o_Command=ADCMD_PERV0L; 

'*===============Fi ni shed with the initialization======*/ 

f i I l_data(sound_data) ; 

sound . i oa_Request . i o_Command=CMD_WRITE; 

sound. ioa_Request.io_Flags=ADI0F_PERV0L| I0F_QUICK; 

sound. ioa_Data=sound_data; 

sound. ioa_Cycles=0; 

sound. ioa_Length=si zeof (sound_data) ; 

sound. ioa_Period= period; 



/* ===Set up the command structures 3 " */ 

f inish=control; 
sound=control; 



285 



Programming Sound 



Listing 7-5. (cont.) 



sound. ioa_Volume=loudness; 

BeginlO(Ssound) ; 

for(i=0;i<30;i++) { 
for(d=0;d<250;d++) 
if (d<60) 

printf ("*"); 
printf ("\n">; 
period-=5; 
loudness — ; 

change sound (&cont rol , loudness, period) ; 

> 

BeginI0(8f inish); 
WaitlO(Ssound); 

CloseDevi ce(8control) ; 



f i I l_data(sound) 
UBYTE *sound; 
{ 

double x; 



for(x=-(PI/2);x<=PI/2;x+=.1) 

*sound= (UBYTE) f loor (100*si n (x) ) ; 



} 



change_sound( loudness , period) 

LIWORD loudness, period; 

C 

control . ioa_Period=period; 
cont ro I . ioa_Volume= loudness; 
BeginlO(Scontrol) ; 



Once a sound is executed, it is possible to change its operating parame- 
ters. Both the volume and the period can be altered. This change is accongl 
plished through a control message to the active audio device. This messagpl 
an IOAudio structure, initialized with both the new values and the con"~, 
information, and attached to the executing channel. The io _Command fieltf 
set to ADCMP_PERVOL to indicate the nature of the command. The * 
Flags field should be set to IOF_ QUICK, but it also may include the ADl 
_SYNCCYCLE. The use of this latter flag ensures that the changes^ 
quested will not occur until the end of a sampling cycle. Without this par 
ter, the changes become effective immediately. 
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Listing 7-6. Starting a note, then varying its period via 
messages sent to the audio device. 



#include <exec/types.h> 
^include <exec/memory.h> 
^include <hardware/custom. h> 
#include <hardware/dmabits.h> 
^include <libraries/dos.h> 
^include <devi ces/audio.h> 
^include <latti ce/stdio.h> 
^include <lattice/math.h> 



extern struct MsgPort *CreatePort () ; 
UBYTE S_data0[32],sunit=0x0f; 

mainO 
< 

int x,y; 

struct IOAudio control, f inish, soundO; 
setup(Scontrol,8f inish) ; 
soundO=control; 

grab_channel (8sound0,8control ,"c1"); 

fi U_data(s_dataO); 

for(;;) < 

printf ("enter period->"); 
scanf ("%d",8x) ; 
if Cx==-1) 
break; 

printf ("enter volume->") ; 
scanf ("%d",8y); 



FORMAT 
ZERO 

ZARAGOZ A 



sound_note (SsoundO, (UWORD) x , (UWORD) y) ; 

BeginlO(SsoundO) ; 
for(;x>=135;x-=28) { 
delayO; 

printfC'new note\n"); 

change sound((UUORD)y, (UWORD) x.Scont rol) ; 

> 

BeginIO(&f ini sh) ; 
WaitlO(SsoundO); 



CloseDevice(Scontrol) ; 

> 

set up (cont rol, finish) 

struct IOAudio *control,*finish; 

< 
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Listing 7-6. (cont.) 



if ((control->ioa_Request.io_Message.mn_ReplyPort=CreatePort("p1 ,, ,0)) 
exit(FALSE); 

if ((f inish->ioa_Request . io_Message.mn_ReplyPort=CreatePort ("p2",0)) 
exi t (FALSE) ; 

cont ro l-> i oa_Request . i o_Message . mn_Node . Ln_Pr i =1 0 ; 
control->ioa_Data=8suni t; 
control->ioa_Length=(ULONG)sizeof (sunit) ; 

i f ( (OpenDevi ce(AUD ION AME.OL, cont ro L ,0L) ) ! =NULL) < 
printf ("Can't open Audio Oevice\n"); 
exi t (FALSE) ; 

} 

/* ===Set up the command structures=== */ 
*f inish=*control; 

f inish->ioa_Request.io_Flags=IOF_QUICK; 

f ini sh->ioa_Request . io_Command=ADCMO_FINISH; 

control. ->ioa_Request . io_Flags=IOF_Ql)ICK; ■ 
cont ro l->i oa Request . i o_Command=ADCMD_PERVOL ; 

> 

fi U_data(sO) 
UBYTE *s0; 
< 

double x; 

for(x=-(PI/2);x<=PI/2;x+=.1) { 
*sO=(UBYTE)f toor(100*sin(x)); 
s0++; 

> 



change_sound( Loudness, period, control) 
UWORD loudness, period; 
struct IOAudio *control; 
{ 

control->ioa_Period=period; 
cont ro I ->ioa_Volume= loudness; 
Begi nIO(cont rol) ; 
WaitlO(control); 

> 

sound_note(chn I, period, loudness) 
struct IOAudio *chnl; 
UWORD period, loudness; 
{ 

chnl->ioa Request. io Command=CMD_WRITE; 
chnl->ioa"Request.iolFlags=ADIOF_PERVOL| IOF_QUICK; 



Listing 7-6. (cont.) 
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chnl->ioa_Data=s_dataO; 
chnl->ioa_Cycles=0; 
chnl->ioa_Length=si zeof (s_dataO) ; 
chnl->ioa_Period= period; 
chn l-> i oa_Vo lume= loudness ; 



grab_channe I (sound, cont ro I , name) 
struct IOAudio *sound,*control; 
char *name; 
{ 

i f ((sound->ioa_Request. io_Message.mn_ReplyPort=CreatePort(nante,0) )==NULL) 
*sound=*control; 

for(i=0;i<1000;i++); MJk jEl 1^ (3 

ZARAfiOZ A 

Listing 7-6 illustrates a program that will start up a sound and then 
vary its period in steps. Since this is a demonstration program, a message is 
displayed on the screen each time the period is changed. In this program, we 
have created three audio structures: 

sound— to start up the initial note on the device 

finish— to stop the note 

control— to carry intermediate messages to the audio device 

The latter two structures are not strictly necessary. One general control 
structure could serve both functions; however, having both increases the 
flexibility of control. At least one structure besides sound is needed; other- 
wise the note cannot be stopped once it is started. A WaitlOO on an IOAudio 
structure, where the ioa_Cycle field has been set to 0, is infinite, at least until 
you lose patience and reboot. When juggling multiple channels, the separate 
structures for control and finish become even more attractive. 

The process of changing a sound's period is simple. Notice the function 
change _sound(). We simply set the new period value and call a BeginlOf) 
followed by a WaitlOO. This function is a general purpose function; it is also 
used to change the volume of the sounded note. A program to change the 
volume over a range going down to a value of 0 is shown in Listing 7-7. 

Listing 7-7. Starting a note and varying loudness via 
messages sent to the audio device. 



^include <exec/types.h> 
^include <exec/memory.h> 
"include <hardware/custom.h> 
"include <hardware/dmabits.h> 
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Listing 7-7. (cont.) 



^include <libraries/dos.h> 

SincLude <devices/audio.h> 

^include <Latti ce/stdio.h> 

^include <lattice/math.h> 

extern struct MsgPort *CreatePort () ; 
UBYTE S_data0[32],sunit=0x0f; 

mainO 
{ 

int x,y; 

struct IOAudio control, f inish.soundO; 
setup(8control ,8f inish) ; 
soundO=controL; 

grab_channel(8sound0,8control ,"c1") ; 

fill_data(s_dataO); 

for(;;) { 

printf ("enter period->"); 
scanf("iW",Sx); 
if <x==-1) 
break; 

printf ("enter volume->"); 
scanf ("%d",Sy); 

sound_note(8sound0, (UUORD)x, (UUORD)y) ; 

BeginlO(SsoundO); 
for(;y>=0;y— ) < 
delayO; 

printf ("new loudness level\n"); 

change sound( (UWORD) y, (UWORD) x.Scontro I) ; 

> 

BeginlO(Sfinish); 
WaitlO(SsoundO); 

} 

CloseDevice(ScontroL) ; 

} 

setup(control, finish) 

struct IOAudio *control,*f inish; 

< 



if ((control->ioa_Request.io Message. mn ReplyPort=CreatePort ("p1",0))~N 
exit (FALSE) ; 

if ((f inish->ioa Request. io Message. mn_ReplyPort=CreatePort("p2",0)> 
exit (FALSE) ; 
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Listing 7-7. (cont.) 



control->ioa_Request . io_Message.mn_Node. ln_Pri=10; 
cont ro L-> i oa_Data=8suni t ; 
control->ioa_Length=(ULONG)sizeof (sunit); 

if ((Open0evice(AUDIONAME,0L, control, OD) (=NULL) { 
printf ("Can't open Audio DeviceW); 
exi t (FALSE) ; 

> 

/* ===Set up the command structures=== */ 
*f inish=*control; 

f inish->ioa_Request. io_F lags=IOF_0UICK; 

f inish->ioa_Request . io_Command=AOCMD_F INISH; 

control->ioa_Request. io_Flags=IOF_QUICK; 
control->ioa Request. io Command=ADCMD PERVOL; 

> 



fill data(sO) 
UBYTi *s0; 
{ 

double x; 

for(x=-(PI/2);x<=PI/2;x+=.1) { 
*sO=(UBYTE)f loor(100*sin(x)); 
s0++; 

} 

> 



FORM A V 
ZERO 

ZARAGOZ A 



change_sound( loudness, period, control) 
UWORD loudness, period; 
struct IOAudio *control; 
{ 

control->ioa_Period=period; 
cont ro l->i oa_Vo I ume= loudness ; 
BeginlO(control); 
WaitlO(control); 

> 

sound_note(chn I .period, loudness) 
struct IOAudio *chnl; 
UWORD period, loudness; 
{ 

chnl->ioa_Request . io_Command=CMO_WRITE; 

chnl->ioa_Request.io_Flags=ADIOF_PERVOL| IOF_QUICK; 

chnl->ioa_Oata=s_dataO; 

chnl->ioa_Cycles=0; 

chnl->ioa_Length=sizeof (s_dataO) ; 

chnl->ioa_Period= period; 

chnl->ioa Volume=loudness; 
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Listing 7-7. (cont.) 



grab_channe I (sound, control .name) 
struct IOAudio *sound ,*cont ro L ; 
char *name; 
{ 

if ((sound->ioa_Request . io_Message.mn_ReplyPort=CreatePort (name.O) )==NULL) 
*sound=*control ; 

} 

delayO 
i 

i nt i ; 

for(i=0;i<1000;i++); 

) 



As might be expected, a volume of 0 shuts off the sound. Listings 
and 7-9 illustrate some interesting variations on these earlier examples! $1 
the former, we vary the volume of a sound using values in an array. This arra 
has been filled using a sine function. In Listing 7-9, the period is varied in the 
same way. These examples serve to illustrate the kind of experimentatio| 
that is possible with the Amiga's sound subsystem. 



- BB 



Listing 7-8. Varying the loudness of a note. Loudness values 
are taken from an array of values. 



((include <exec/types.h> 

((include <exec/memory.h> 

/(include <hardware/custom. h> 

/(include <hardware/dmabits.h> 

/(include <libraries/dos.h> 

/(include <devices/audio.h> 

/(include <lattice/stdio.h> 

/(include <lattice/math.h> 

extern struct MsgPort *CreatePort () 
UBYTE s_dataOC32] , suni t=0x0f ; ' ^ ^ (V 

mainO 
{ 

int x, j ,vol[315]; 

struct IOAudio cont ro I , f i ni sh , soundO; 



m 



setup(8control,8f inish) ; 
soundO=control; 

grab_channel(8sound0,8control,"c1"); 



fi U_data(s_dataO) ; 
f i I l_array(vol) ; 



for<;;) { 
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Listing 7-8. (cont.) 



printf ("enter period->"); 
scanf ("Xd",8x); 
if (x==-1) 
break; 

sound_note (SsoundO, (UWORD) x , (UUORD) vo I CO] ) ; 

BeginIO(8soundO) ; 
for(j=1; j<315;j++) { 
delayO; 

printf ("vol [Xdl«Xd\n",J, volt jl); 

change_sound ( (UWORD) vo I [ j ] , (UUORD) x , Scont ro I ) ; 

BeginI0(8f inish); 
Wait 10 (SsoundO); 

> 

CloseDevice(Scontrol) ; 

> 

setup (control, finish) 

struct IOAudio *control,*f inish; 

if((control->ioa_Request.io_Message.mn_ReplyPort=CreatePort("p1",0))==NULL) 

6X1 t (FALSE) j 

if ((finish->ioa_Request.io_Message.mn_ReplyPort=CreatePort("p2",0))==NULL) 
6X1 "t C F A i_ S £ ) f 

control->ioa_Request.io_Message.mn Node. In Pri=10; 

control->ioa_Data=8sunit; 

cont rol->ioa_Length=(ULONG) si zeof (suni t) ; 

if C(0penDevice(AUDI0NAME,0L, control, 01)) !=NULL) { 
printf ("Can't open Audio Device\n"); 
exit (FALSE); 

> 

/* ====set up the command structures=== */ 
*f inish=*control; 

finish->ioa_Request. io_Flags=I0F_0UICK; 
finish->ioa_Request.io_Command=ADCMD_FINISH; 

control->ioa_Request.io_Flags=IOF_OUICK; 
^control->ioa_Request.io_Command=ADCHD_PERVOL; 

f iU_data(sO) 
UBYTE *s0; 

double x; 
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Listing 7-8. (cont.) 



for(x=-(PI/2);x<=PI/2;x+=.1) { 
*sO=(UBYTE)f loor(100*sin(x)); 
s0++; 

> 



change_sound( loudness, period, control) 
UWORD loudness, period; 
struct IOAudio *control; 

c 

control->ioa_Period=period; 
cont rol->ioa_Vo lume= loudness; 
BeginlO(control) ; 
WaitlO(control); 

} 
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sound_note(chn I, period, loudness) 
struct IOAudio *chnl; 
UWORD period, loudness; 

{ 

chnl->ioa_Request . io_Command=CMD_WRITE; 

chnl->ioa_Request.io.Flags=ADIOFlPERVOL| IOF_QUICK; 

chnl->ioa_Data=s_dataO; 

chnl->ioa_Cyc tes=0; 

chnl->ioa_Length=sizeof (s_dataO) ; 

chnl->ioa_Period= period; 

chnl->ioa_Volume= loudness; 



w 



I 



grab_channe I (sound , cont ro I , name) 
struct IOAudio *sound,*control; 
char *name; 
{ 

i f ( (sound->i oa_Request . io_Message. nin_Rep lyPort=CreatePort (name.O) )==NULC i 
*sound=*control; 

} 

delayO 
C 

int i; 

for(i=0;i<1000;i++); 

> 

fi L L_array(sO) 
int *s0; 
C 

double x; 



for(x=-PI;x<=PI;x+=.02) { 
*sO=(int)f loor(25*sin(x)+25); 
s0++; 

> 
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Listing 7-9. Varying the period of a note. Period values are 
taken from an array of values. 

#include <exec/types.h> 

#include <exec/memory. h> 

#include <hardware/custom. h> 

flinclude <hardware/dmabits.h> 

^include <libraries/dos.h> 

^include <devices/audio.h> 

/(include <lattice/stdio.h> 

/(include <latti ce/math.h> 

extern struct HsgPort *CreatePort () ; 
UBYTE s_data0C32],sunit=0x0f : 

mai n() 
{ 

int x,y,j,volC63]; 

struct IOAudio cont ro I , f i ni sh , soundO; 
setup (Scont rol ,Sf inish) ; 
soundO=control; 

grab_channel (SsoundO.Scontrol ,"c1") ; 

fi U_data(s_dataO); 
fi ll_array(vol); 

for(;;) { 

printf ("enter periocl->"); 
scanf("Xd",8x); 
if (x==-1) 
break; 

printf ("enter volume->"); 
scanf ("Xd",8y); 

sound_note(SsoundO, (UWORD) x, (UWORD) y) ; 

BeginlO(SsoundO) ; 
for(j=1;j<63;j++) { 
delayO; 

printf ("vol [%d]=Xd\n",j, vol Cj]) ; 
change_sound((UWORD)y, (UWORD) vo I [ j ] ,8cont rol) ; 

> 

BeginI0(8f inish); 
WaitI0(8sound0); 

} 

CloseDevice (Scont rol); 

} 

setup (cont rol, finish) 

struct IOAudio *control ,*f i ni sh; 

{ 
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Listing 7-9. (cont.) 



if <(control->ioa_Request.io_Message.mn_ReplyPort=CreatePort C"p1",0))==NULL) 
exit (FALSE); 

if ((finish->ioa_Request.io_Message.mn_RepLyPort=CreatePort( ,, p2",0))==NU 
exi t (FALSE) ; 

cont rol ->ioa_Request. io_Mes sage. mn_Node. ln_Pri=10; 
cont ro L->i oa_Data=&suni t ; 
control->ioa_Length=(ULONG)sizeof (sunit); 

i f ( (OpenDev i ce ( AUD IONAHE , OL , cont rol ,0L) ) ! =NULL) { 
printf ("Can't open Audio DeviceNn"); 
exi t (FALSE) ; 

> 

/* ===Set up the command Structures=== */ 
*f ini sh=*controL; 

f i ni sh->i oa^Request . i o_F lags=IOF_QUICK; 
f ini sh->ioa_Request . io_Command=ADCMD_FINISH; 

control->ioa_Request.io_Flags=IOF_QUICK; 
cont rol->ioa_Request.io_Command=ADCMD_PER VOL; 



fi tl_data(sO) 
UBYTi *s0; 
( 

double x; 

for(x=-(PI/2);x<=PI/2;x+=.D C 
*sO=(UBYTE)f Loor(100*sin(x)); 
sO+; 

} 

> 



O 



a 



change_sound( loudness, period, cont rol) 
UWORD loudness, period; 
struct IOAudio *control; 
( 

control->ioa_Period=period; 
cont ro l->i oa_Vo lume= loudness ; 
BeginlO(control); 
WaitlO(control); 

> 

sound_note(chn I, period, loudness) 
struct IOAudio *chnl; 
UWORD period, loudness; 
{ 

chnl->ioa Request. io Command=CMO_WRITE; 
chnl->ioalRequest.io_Flags=ADIOF_PERVOL| IOF_QUICK; 
chnl->ioa Data=s_dataO; 
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Listing 7-9. (cont.) 



chnl->ioa_Cycles=0; 
chnl->ioa_Length=si zeof (s_dataO) ; 
chnl->ioa_Period= period; 
chnl->ioa Volume=loudness; 

> 

• g rab_channe I (sound , cont ro I , name) 
struct IOAudio *sound,*control; 
char *name; 
< 

if ((sound->ioa_Request.io_Message.mn_ReplyPort=CreatePort (name,0))==NULL) 
*sound=*control; 

> 

delayO 
{ 

i nt i ; 

for(i=0;i<1000;i++); 

} 

f i U_array(sO) 

int *s0; 

I 

double x; 

for(x=-PI;x<=PI;x+=.1) { 

*sO=(int)f loor(50*sin(x)+50) ; 
s0++; 

> 



Multichannel Sound 

The Amiga has four independent sound channels attached to two output 
jacks. More complex sound-oriented programming involves the manipulation 
of more than one of these channels at a time. This added level of complexity 
requires careful consideration of coordination and synchronization. 

When you open the audio device, you specify which of the four channels 
you require. These channels are specified in the bit map that is assigned to 
the ioa_Data field. Once this has been done, however, you can still send 
command messages to this device, that are specifically aimed at a particular 
channel. This information is specified in the ioa_Request.io_Un.it field of the 
audio structure. By exercising this control, you can produce interesting ef- 
fects, such as stereo sound. 

Listing 7-10 contains a program that illustrates this kind of control. This 
program requires the attachment of two speakers to the two audio jacks on 
the Amiga. It sounds a note first on the left speaker and then moves it to the 
right speaker. 
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Listing 7-10. Playing a note first on the left channel, then 

the right. 



#include <exec/types.h> 
^include <exec/memory.h> 
^include <hardware/custom.h> 
^include <hardware/dmabits.h> 
^include <l i brari es/dos . h> 
^include <devi ces/audio.h> 
^include <lattice/stdio.h> 
#include <latti ce/math.h> 

extern struct MsgPort *CreatePort () ; 
UBYTE s_dataOC32] ,s_data1 [32] ,sunit=0x0f , 
mapleft=0x09,mapright=0x06; 

mainO 
{ 

int x,y,j; 

UBYTE unitO.unitl; 

struct IOAudio control, finish, soundO.soundl , ■ 
setup(8control,8f inish,8unit0,8unit1) ; 
soundO=control; 

soundO. i oa_Request . io_Uni t=uni tO; 
sound1=control; 

soundl . ioa_Request . io_Uni t=uni t1 ; 



grab_channel (8soundO,8controL,"c1") ; 
grab_channel(8sound1 ,8control,"c2"); 

fi lL_data(s dataO); 
fi U_data(s_data1); 

for<;;) { 

printf ("enter pen'od->"); 
scanfC"Xd",8x); 
if (x==-1) 
break; 

printf ("enter volume->") ; 
scanf ("%d",8y); 

sound_note(8sound0, (UWORD) x , (UWORD) y) ; 
sound_note(8sound1 , (UUORD)x, (UUORD)y) ; 

BeginlO(SsoundO) ; 
WaitlO(SsoundO) ; 

BeginIO(8sound1) ; 
WaitIO(8sound1); 

} 
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CLoseDevi ce(Scontrol) ; 

> 

set up (cont ro I, f inish,unit0,unit1) 
struct IOAudio *controL,*f inish; 
UBYTE *unit0,*unit1 ; 

if ((control->ioa_Request.io Message. nn ReplyPort 
=CreatePort("p1",0))==NULL)exit (FALSE); 

if ((finish->ioa_Request.io Message. mn ReplyPort 
=CreatePort("p2",0))==NULL)exit (FALSE) ; 

control->ioa_Request.io Message. ran Node. In Pn"=10- 
control->ioa_0ata=8sunit; " ' 

control->ioalLength=(ULONG)sizeof(sunit); 

i f ((OpenDev ice (AUDIONAME.OL, control, 0D) i=NULL) { 
printf ("Can't open Audio Device\n"); 
exit (FALSE); 

} 

*unitO=((U8YTE)control->ioa_Request.io Unit 8 mapleft)- 
*un l t1 = ((UBYTE)control->ioa.Request.io>it 8 mapHght); 

/* ===Set up the command structures=== */ 
*f inish=*control; 

f inish->ioa_Request . io_Flags=IOF QUICK; 

f inish->ioa_Request . io~Command=AOCMD_F INISH ; 

control->ioa_Request.io_Flags=IOF QUICK; 
^control->ioa_Request.io"Command=ADCMD_PERVOL; 

fill data(sO) 
UBYTE *s0; 

double x; 

FOB M IT 
ZERO 

ZARAGOZA 



for(x=-(PI/2);x<=PI/2;x+=.1) { 
*sO=(UBYTE)f loor(100*sin(x)); 
s0++; 

} 

> 

change_sound( loudness, period, control) 
UWORD loudness, period; 
struct IOAudio *control; 

control->ioa_Period=period; 
cont rol->ioa~Vo lume= loudness; 
BeginlO(control) ; 
WaitlO(control); 
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Listing 7-10. (cont.) 



scund_note(chnl, period, loudness) 
struct IOAudio *chnl; 
UVORD period, loudness; 

i chnl->ioa_Req U est^ > o_Con.m8nd=CMD.WRITE; 

chnl->ioa Request. 10 _Flags-ADIOF_PERVOL| iur_ 
chnl->ioa Data=s_dataO; 
chnl->ioa.Cycles=1000; 
chnl->ioa length=sizeof(s_dataO). 
chnl->ioa Period= period; 
chnl->ioa_Volume= loudness; 

> 

grab channeKsound, control, name) 
struct IOAudio *sound,*control; 
char *name; 
< 

i f ( (sound- „port = CreatePort (name.O) ) — NUL 

Jioa_Request.io_Message.ran_ReplyPort create 

*sound=*control; 

} 

delayO 

{ 

int i; 

for(i=0;i<1000;i++); 



Each of these 3 erves as a mask to block out aU but those bits ^ 

channels on their respective ^J^J^^l****,. 
bitwise "and" operator combines each of these b its ^ a P At the 
Sg io Unit field to extract the appropriate ^ identical 
2s procedure, each audio structure contams those 
that would result from opening the device and spmfj mg X 

Once we have properly initialized our two 
sound. First we call BeginlOO f**^"£^J2k 
WaitlOO until this note is finished, then . does a f^nWO « 
soundl. To simplify this example, we f the , | 

creating a continuous sound and ^ ^Here we| 
In Listing 7-11, we have a more complex situatic > ■ 
on the left speaker, as before then ^play ■* « bo h ^ 
Finally, we finish it up on the right speaker We crea ^ 
structures: control, finish, soundO, and soundl. We set the 
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Figure 7-10. Values for the variables mapleft and mapright 



7 


6 


5 


4 


3 


2 


1 


0 


0 


0 


0 


0 


1 


0 


0 







p» mapleft 



Channel 0 



0 mapright 



Channel 3 



Channel 1 
Channel 2 



as before. We initiate the sound by doing a BeginlOO, using soundO, but, 
instead of performing a WaitlOO on this command, we delay for a set period 
and do another BeginIO( ) with soundl. After another delay, we send a finish 
message to stop the sound in the left speaker. Finially, after a third delay, we 
send a finish command to the remaining channel. 

Listing 7-1L Playing a note first on the left channel, then on 
both, then on the right channel. The finish command is used. 



^include <exec/types.h> 
^include <exec/memory.h> 
#include <hardware/custom. h> 
^include <hardware/dmabi ts.h> 
^include <l i brari es/dos . h> 
^include <devices/audio.h> 
#include <lattice/stdio.h> 
^include <lattice/math.h> 

extern struct MsgPort *CreatePort O ; 
UBYTE s_data0[32],s_dataU32],sunit=0x0f , 
mapleft=0x09,mapright=0x06; 

mainO 



FOB MAT 
ZERO 

ZARAGOZA 



int x,y,j; 

UBYTE unit0,unit1; 

struct IOAudio control, finish, soundO, soundl; 

setup(&control,8finish,SunitO,Sunit1); 

soundO=control; 

soundO. ioa_Request. io_Unit=unitO; 
soundl =contro I; 

soundl . ioa_Request . io_Unit=unit1 ; 



9rab_channel (SsoundO,Scontrol ,"c1") ; 
9'"ab_channe I (Ssoundl ,8cont ro I , "c2") ; 
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Listing 7-11. (cont.) 



fi Ll_data(s dataO); 
fill_data(s~data1); 

for<;;) { 

printf ("enter period->") ; 
scanf ("%d",Sx); 
if(x==-1) 
break; 

printf ("enter volume->"); 
scanf ("%d",8y); 

sound_note(8sound0, (UWORD)x, (UWORD)y) ; 
sound_note(8sound1 , (UWORD) x, (UWORD) y) ; 

BeginlO(SsoundO) ; 
delaydOOOOO); 
BeginIO(8sound1); 
delaydOOOOO); 

f inish. ioa_Request.io_Unit=unitO; 
BeginIO(8f inish) ,• 
WaitIO(Sfinish); 
delaydOOOOO); 

f inish. ioa_Request. io_Um't=unit1 ; 
BeginI0(8f inish) ; 
WaitlO(Sfinish); 



* S * ° 




^CloseDevice(8control) ; 

setup ( cont ro I, f inish.unitO.unitD 
struct IOAudio *control,*f inish; 
UBYTE *unit0,*unit1; 

if ((control->ioa Request. io_Message.mn_ReplyPort 
=CreatePort("p1",0))==NULL) exit (FALSE); 

if ((finish->ioa Request. io Message. mn ReplyPort 
=CreatePort("p2",0))==NULL)exit(FALSE); 

control->ioa_Request. io_Message.mn Node. ln_Pri=10; 
control->ioa_Data=8sunit; 
control->ioa_Length=(ULONG)sizeof (suni t) ; 

if ((OpenDevice(AUDIONAME,0L, control, OD) !=NULL) { 
printf ("Can't open Audio DeviceNn"); 
exit (FALSE); 

> 

*unitO=((UBYTE)control->ioa Request. io_Unit 8 mapleft); 
*unit1=((UBYTE)control->ioa_Request.io_Um't 8 mapright); 



/* ===set up the command structures=== */ 
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Listing 7-11. (cont.) 



*f inish=*control; 

f ini sh->ioa_Request . io_Flags=IOF QUICK; 

f ini sh->ioa_Request . io~Command=ADCMD_F INISH; 

control->ioa_Request . io_Flags=IOF QUICK; 
^control->ioa_Request .io_Command=ADCMO_PERVOL; 
fill data(sO) 
UBYTE *s0; 
< 

double x; 

for(x=-(PI/2);x<=PI/2;x+=.1) { 
*sO=(UBYTE)f loor(100*sin(x)); 
s0++; 

> 

> 

change_sound( loudness, period, control) 
UWORD loudness, period; 
struct IOAudio *control; 
< 

control->ioa_Pen'od=period; 
cont ro I ->ioa_Vo I ume= loudness, • 
BeginlO(control) ; 
WaitlO(control) ; 

sound_note (chn I .period, '.oudness) 
struct IOAudio *chnl; 
UWORD period, loudness; 
{ 

chnl->ioa_Request . io_Command=CMD WRITE; 

chnl->ioa_Request .io2Flags=ADIOF~PERVOL| IOF_QUICK; 

chnl->ioa_Data=s_dataO; 

chnl->ioa~Cycles=0; 

chnl->ioa_Length=si zeof (s_dataO) ; 

chnl->ioa_Period= period; 

chnl->ioa Volume= loudness; 

> 

grab_channel (sound, control , name) 
struct IOAudio *sound,*control; 
char *name; 
{ 

if ((sound->ioa_Request . io Message. mn_ReplyPort 
^ =CreatePort(name,0))==NULL)*sound=*control; 

delay (intv) 
long intv; 
{ 

long i ; 
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Listing 7-11. (cont.) 



for(i=0;i<=intv;i++) 



In our last example, Listing 7-12, we produce a sound using all fomi 
sound channels. This produces a full, rich, and complex tone. Two channels-| 
0 and 2— sound from the left speaker, while the two remaining ones— 1 and 
3— are attached to the right speaker. Our complement of audio structure! 
includes control and finish, as well as four sound structures: sO, si, s2, and sat 
Each of these latter structures is attached to a particular unit of the audif 
device. Once we initialize each one with the note we wish to play, we begi 
them one at a time. For effect, we start sO then s2, and finally si and s3. || 
channels are shut down with a finish command, specifically sent to each i 
in reverse order. 

Listing 7-12. Using all four channels to produce sound. 

Hh'nclude <exec/types . h> 

^include <exec/memory . h> 

#include <hardware/custom.h> 

#include <hardware/dmabits.h> 

^include <libraries/dos.h> 

#include <devi ces/audi o. h> 

^include <lattice/stdio.h> 

^include <latti ce/math.h> 

extern struct MsgPort *CreatePort () ; 

UBYTE S _data0[32],s_data1[32],s_data2[32],s_data3[32], 
sum' t =0x0 f ; 



mainO 
{ 

int x,y,j; 

UBYTE u0=0x01 ,u1=0x02,u2=0x08,u3=0x04; 
struct IOAudio control, finish, sO, s1 ,s2,s3; 



setup (&cont ro l ,8f inish) ; 



sO=control; 

sO. i oa_Request . i o_Uni t=u0; 
s1=controL; 

s1 . i oa_Request . i o_Uni t=u1 ; 
s2=controL; 

s2. ioa_Request. io_Unit=u2; 
s3=controL; 

s3 . i oa_Request . i o_Uni t=u3 ; 
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Listing 7-12. (cont.) 



grab_channel (Ss0,8control,"c1") 
grab_channel (8s1 ,8controL,"c2") 
grab_channel (8s2,8control,"c3") 
grab_channe I (8s3 , Scont ro I , "c4") 

fi U_data(s dataO); 
fill_dataCs~data1); 
fill_data(s data2); 
fi U_data(s~data3); 

/* left channel setup */ 

sound_note(8s0, (UW0R0)508, (UUORD)30) • 
sound_note(8s2, (UW0RD)254, (UWORD)30) ; 

/* right channel setup */ 

sound_note(8s1 , (UU0RDK28, (UWORD)30) • 
sound_note(8s3, (UW0RD)214, (UUORD)30) ; 

BeginlO(SsO); 

delayOOOOOO); TTi^W* H w A nn 

BeginI0(8s2); FORMAT 
delay (100000); 

BeginlO(Ssl); ^ p» V? O 

delavdonnnm- *- J V> 



delayOOOOOO); 
BeginIO(8s3); 
delay (500000); 



8e ? inI ?^) ; ZARAGOZ A 



finish. ioa Request. io Unit=u3- 
BeginIO(8f inish); 
WaitI0(&f inish); 

f inish. ioa_Request. io Unit=u1 • 

BeginI0(8finish); 

WaitI0(8finish); 

f ini sh. ioa_Request . io Uni t=u2- 

BeginI0(8finish); 

WaitlO(Sfinish); 

fini sh. ioa_Request . io Unit=u0- 
BeginI0(8f inish) ; 
WaitI0(8f inish) ; 



j CloseDevice(8control); 

setup (control, finish) 

struct IOAudio *control,*finish; 

if((control->ioa.Request.io_Message.mn_ReplyPort 
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Listing 7-12. (cont.) 



=CreatePort ("p1 ",0> )==NULL) exit (FALSE); 

if ( (f ini sh->ioa Request . io_Message.mn RepLyPort 
=CreatePort("p2",0))==NULL) exit (FALSE); 

cont ro l->ioa_Request . i o_Message.mn_Node. ln_Pri =10; 
controL->ioa_Data=Ssuni t; 
control->ioa~Length=(ULONG) si zeof (suni t) ; 

i f ( (OpenDevi ce(AUDIONAME,0L, control ,0L) ) !=NULL) { 
printf ("Can't open Audio DeviceW); 
exit (FALSE) ; 

> 

/* ===Set up the command structures=== */ 
*f inish=*control; 

f ini sh->ioa_Request . io_Flags=IOF_QUICK; 

f ini sh->ioa~Request . io_Command=ADCMD_FINISH; 

control->ioa_Request . io_Flags=IOF_QUICK; 
control->ioa~Request . io_Command=ADCMD PERVOL; 

> 

f i 11 data(sO) 
U8YTE *s0; 
{ 

double x; 

for(x=-(PI/2);x<=PI/2;x+=.D i 
*sO=(UBYTE)f loor(10l>sin(x)); 
s0++; 

> 



change_sound( loudness, period, control) 
UWORD loudness, period; 
struct IOAudio *control; 
{ 

contro l->i oa_Period=peri od; 
cont ro I ->ioa_Volume= loudness ; 
BeginlO(control) ; 
WaitlO(control); 

> 

sound_note(chnl .period , loudness) 
struct IOAudio *chnl; 
UWORD period, loudness; 
< 

chnl->ioa_Request. io Command=CMD_WRITE; 
chnl->ioa_Request.io>lags=ADIOF_PERVOL| IOF_QUICK; 
chnl->i oa_Data=s_dataO; 
chnl->ioa_Cycles=0; 
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Listing 7-12. (cont.) 



chnl->ioa_Length=sizeof (s dataO); 
chnl->ioa_Period= period; - 
chnl->ioa_Volume=loudness; 

grab_channe I (sound, contro L, name) 
struct IOAudio *sound,*control; 
char *name; 

if ((sound->ioa_Request. io Message. mn ReplyPort 
=CreatePort(name,0))==NULL)*sound=*control; 

delay (intv) 
long intv; 

long i; 

for(i=0;i<=intv;i++) 

> 



Summary 

Through the examples in this chapter, you have seen several ways to access 
the sound subsystem on the Amiga. You can go from the very simple- 
sounding a note on a single channel-to the complex-using all channels to 
produce a full, stereophonic sound. Because these channels are accessed 
through a standard device, they are readily available in the Amiga's mul- 
titasking environment. Thus, sound can be added as an incidental effect to an 
application (e.g., a game), or it can be added to a graphics program to produce 
an enhanced multimedia effect. 

There are other capabilities of the sound subsystem that are beyond the 
scope of this chapter's discussion. For the programmer willing to go deep into 
the hardware level, it is possible to set up the sound circuitry so that one 
channels output will modulate another. Both amplitude and frequency modu- 
lation are possible. In addition, as with all devices that can participate in the 
Amiga s multitasking, you can coordinate the audio device among competing 
tasks. It is possible to lock the channels and use allocation commands to 
arbitrate between users of different priorities. It is even possible, with some 
add-on hardware, to use the Amiga in a MIDI network where it can function 
as both a controller and as another instrument. 

The sound capabilities of the Amiga make it an outstanding machine for 
any kind of music programming tasks. As we have seen, it is a powerful 
programming tool, yet that power is easy to access. 
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Although it is possible to create speech just by manipulating the 
Amiga's sound subsystem, the necessity for such direct and low-level access 
has been obviated by the creation within the operating system of a "speech 
synthesis" subsystem. This is yet another example of the advanced nature of 
the Amiga. The speech device is on the s^mejevel of access as the more" 
mundane printer drivers! ^_J> JJ^ T\ f r r—^ 

Phonemes and Syllables ^ E R Q 

*A RAGOZ A a 

Human speech is a function of the physical characteristics which produce il 
the hardware, as it were. It is necessary to create a simulation of this bi| 
ware to create the oscillating current that drives the loudspeakers, whi 
finally allow you to hear the sounds. However, first you need some kind 
connection with the printed word that will drive this synthesis. WhalP 
want is the ability to type a line or a paragraph of text and have the 
speak it. The connecting link is the phoneme; this is a higher level 
tion than the actual sounds themselves. 

A phoneme is a basic unit of linguistic sound, which is peculiar to and 
defines a particular language. The human vocal tract can make a large v 
ety of noises, tones, and other sonic objects. Each human language restr 
itself to a very small subset of these sounds; these are the phonemes. S; 
synthesizers, then, need only be able to generate a small set to create " 
ble speech. 

The phoneme is also related to the written word. There is not n 
a one-to-one correspondence between syllables and phonemes, bu„ 
often at least a rough correlation. Besides creating the sounds, * 
synthesis system must be able to translate the written text, syllab 
syllable, into proper phonemes, which can then' be handled by the 
generator subsystem. i'^" 

Each of these problems— translation and speech— is a signific 
The algorithms are not trivial, and, in fact, there is a great 
versy over which approaches are most proper. The Amiga 
and speech by creating two related subsystems: 

- 

1. The translator library handles the encoding of the written WO 
phonemes. 



2. The narrator device produces the speech. 

In the following pages we will concentrate on how to use these two/ 
both independently and together. 



The Translator Library 



The first task of the speech producing process is to divide the writl 
into its constituent phonemes. The translator library is a disk-resid| 
that can help accomplish this job. It takes as input a string r 
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lengths. The translator library is opened within the scope of the function, the 
translation is made, and then the library is closed. The error checking in the 
get ^phoneme! ') function is 'minimal; it returns an integer value indicating 
success or failure. In the program example, we close the library immediately 
after the translation into phonemes, because it is a good idea to keep hold of a 
resource such as a library for as little time as possible. This increases the 
efficiency of memory usage, which, in a multitasking environment, in turn 
makes for fewer delays and faster program execution. In fact, closing a 
library doesn't necessarily mean that the library code is swapped out to disk? 
If the space in memory is not needed, it remains there, waiting for its next 
use. 

Listing 8-1. Use of the translator library to convert a string of 
characters into a string of phonemes. 

#define ERR 1 
#define SUCCESS 0 

^include <exec/types.h> 

^include <exec/exec.h> 

#include <exec/nodes.h> 

^include <exec/lists.h> 

^include <exec/memory.h> 

^include <exec/i nterrupt s . h> 

#include <exec/ports.h> 

^include <exec/Libraries.h> 

^include <exec/io.h> 

^include <exec/tasks.h> 

^include <exec/execbase.h> 

#i nc Lude libraries/ trans lator.h> 

^include <lattice/stdio.h> 



B R O 
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struct Library *Trans latorBase; 
extern struct Library *0penLibraryO ; 

mainO 



UBYTE in_string[80: ,out_string[300] ; 



printf ("enter string "); 
scanf ("%s",in_string) ; 



i f(get_phoneme(i n_st ring, strlen(in_st ring) ,out_st ring, 300)==ERR) 
exi t (FALSE) ; 

printf ("\n\nThe phoneme translation of Xs is %s\n", in_st ri ng.out 
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Listing 8-1. (cont.) 



get_phoneme(in, inlen,out,out len) 
UBYTE *in,*out; 
SHORT inlen.out len; 
{ 

TranslatorBase=(struct Library *) 

OpenLibrary ("translator. library", 1); 

i f (Trans latorBase==NULL) 
return(ERR); 

if ((Translate (in, in len, out, out ten)) i=0) 
return(ERR) ; 

CloseLibrary(TranslatorBase) ; 
return(SUCCESS); 

> 



sion J^hP T 6 3 th3t n0t be ° bvi0us from either the ^scus- 

sion of the Translate!) function or its program example. Translate!) always 
works on a sentence-a string of text. If a single word or even a single sound 
s translated, it is translated as a sentence. This has an effect on the intona- 
tion of the word when it is finally produced by the narrator device. Once a 
string of phonemes has been produced by this function, the string can be 
edited as any other text string; thus, you can fine tune the speech that is 
finally uttered without having to create your own translation algorithms. 

The Narrator Device 

InMT St ?u °T y ° U haVe translated text a phonetic representation, is 
to call up the Amiga s hardware, in order to pronounce each one of the 
phonemes^This capability is contained in a specialized device driver the 
Narrator There are many advantages in making this a device driver; a major 
one is that as a device driver, the Narrator can participate fully in the 
Amiga s multitasking environment. The processes producing speech can run 
m the background ,n concert with other system processes rather than taking 
over the entire machine. Possibilities are endless, but a particular combina 
tion that comes readiy to mind is the integration of sound with the fine 
graphics displays avadable on the Amiga. 

<,hnw ASide -S° m u hG somewhat flash y tad practical) graphics and sound 
annlr/rf ° th ™ t °? d (but no less important) possibilities become 
apparent. Sound can be wedded to a database program and thus can tell you 
what is found in a search. Speech in conjunction with a program help facility 
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can add an important dimension of performance to an application program 
The narrator device, although simple in operation, is an important subsystem 
on the Amiga and one that is not often found on microcomputers. 

Splitting the two functions— speech and translation— is yet another indi- 
cation of the sophistication of the Amiga. This allows a great degree of 
flexibility. For example, if you have a need to say only a few phrases or 
repeated sentences, you can save yourself the overhead of the translator 
library, and hard code the phonetic representation into your program. If you 
need an overall conversion facility, it is available. You can also replace the 
translation facility with one of your own design, or even add layers of prepro- 
cessing. I 

Since the Narrator is a device, access is through the Amiga's message 
facility. You command the device by sending messages, and it returns mesl 
sages to indicate the completion of the required task or to report important' 
status information. The first level of access is through a modified message: 
structure: 



struct narrator_rb { 

struct lOStdReq message; 
UWORD rate, 

pitch, 

mode, 

sex; 

UBYTE *ch_masks; 
UWORD nm_masks, 

volume, 

sampf req; 
UBYTE mouths, 

chanmask , 

numchan, 

fill; 

>; 



Message is a standard I/O structure to interface with the message pass 
system. The ch_masks and nm_masks are concerned with channel alloca 
in the audio device. Note that chanmask and numchan are set by the sys 
rather than the program. The mouths field is used in conjunction with 
related mouth_rb structure; we will talk more about this in a moment! 

The rate field sets the speed of the uttered speech; it is measurg 
words per minute. The range of this parameter varies from 40 to 400 WC 
per minute. The default rate is set at 150. The volume field ranges from i 
64 and affects the loudness of the speech sounds. The default value is 
while a value of 0 indicates the device is turned off. 

The mode field affects the intonation and stress of the artificial spe 
produced. There are two defined modes: 

NATURALFO produces an inflected speech that attempts to mom 
ordinary English speaker's natural intonations. 

ROBOTICF0 sets the Narrator to produce speech in a monotone— a 
steady, unvarying pitch with no inflection. 
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The default mode is NATURALFO. 

Three fields can affect the sound quality of the Amiga's synthetic 
speech. The pitch field sets the base line frequency of the narrator device. 
Inflected speech varies around this value as a center point. If the mode is set 
to produce a monotone voice, this frequency is used without any variation. 
The range of the pitch field is from 65 to 320. The sex field takes either 
MALE or FEMALE; these defined constants cause the narrator device to 
produce speech that is characteristic of a man or a woman. The practical 
effect of this field is the production of a sound that is higher or lower. The sex 
field sets the overall frequency of the sound; the pitch value is a type of fine 
• tuning control that varies the sound within this range. 

Finally, sampfreq sets the sampling frequency of the audio device when 
it is rendering the speech sounds. Varying this between its extremes of 5000 
and 28000 also indirectly affects the overall sound. Some interesting effects 
can be produced by playing with this field, but bear in mind that this is not 
the main purpose for the field. Its default value is 22200. 

Listing 8-2 illustrates a program that converts a single line of text into 
an utterance. It consists of two functions. 

1. get_phoneme() accesses the translator library. 

2. talk_to_me() activates the narrator device. 

The former has been imported from an earlier example (Listing 8-1); it trans- 
lates the entered string into a phonetic representation and returns the result 
in the string variable out_string. 

Listing 8-2. Use of the translator library and the narrator 
device to produce speech phonemes. 



#define ERR 1 
tfdefine SUCCESS 0 
fldefine REV 0 



^include <exec/types.h> 
^include <exec/exec.h> 
^include <exec/nodes.h> 
#include <exec/ Li sts .h> 
^include <exec/memory.h> 
^include <exec/interrupts.h> 
^include <exec/ports . h> 
^include <exec/libraries.h> 
^include <exec/io.h> 
#include <exec/tasks . h> 
^include <exec/execbase.h> 
^include <libraries/translator.h> 
^include <devices/audio.h> 
^include <devices/narrator.h> 
^include <latti ce/stdio.h> 



struct Library *Trans LatorBase=NULL; 
extern struct Library *0penLibraryO ; 
struct MsgPort *WPort,*RPort; 



p ORMAT 

ZARAOOZ a 
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Listing 8-2. (cont.) 



extern struct IORequest *CreateExt IOC) ; 
extern struct Library *OpenLi brary () ; 
struct narrator_rb *wmes; 
struct mouth_rb *rmes; 

BYTE audChanMasksl"]={3,5,10,12>; 

mainO 
{ 

UBYTE in_string[80] ,out_string[30Q] ; 

pri ntf ("enter string "); 
gets(in_string) ; 



■ 

if (get phonemeO'n string, strlenO'n string), out string, 300)==ERR)s 
exi t (FALSE) ; 

if (ta Lk_to_me(out string)==ERR) 
exit (FALSE) ; 

CloseOevi ce(wmes) ; 



get phonetne(i n, i n ten, out ,out len) 
UBYTE *in,*out; 
SHORT inlen.outlen; 
{ 



Trans LatorBase=(struct Library *) 

Open Li brary ("trans Lator . I i brary", REV) ; 

if (Trans latorBase==NULL) 
return(ERR) ; 

if ((TransLate(in,inlen,out,outlen)) !=0) 
return(ERR); 



CloseLibrary(TransLatorBase) ; 
return(SUCCESS); 



ta I k_to_nie (speech) 
UBYTE *speech; 
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if ((RPort=(struct MsgPort *)CreatePort(0,0))==NULL) 
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Listing 8-2. (cont.) 



return(ERR) ; 

if ( (wmes=(struct narrator rb *) 

CreateExt 10 (UPort, si zeof (struct narrator_rb)))==NULL) 
return(ERR) ; 

if ((rraes=(struct mouth_rb *) 

CreateExtIO(RPort,sizeof (struct narrator rb)))==NULL) 
return(ERR) ; 



wmes->message.io_Command=CMD_URITE; 
wmes->message. io_Data=(APTR) speech; 
wmes->message.io_Length=str Len (speech) ; 
wmes->ch_masks=audChanMasks; 
wmes->nm_masks=sizeof (audChanMasks) ; 



if (OpenDev ice ("narrator. device", 0,wmes,0) 1=0) 
return(ERR) ; 



wmes->mouths=0; 

wmes->volume=32; 

wmes->rate=20; 

wmes->sex=MALE; 

wmes->pitch=DEFPITCH; 

DoIO(wmes) ; 

return (SUCCESS); 

> 



zero 
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The function talk _to _me() performs all the necessary steps to set up 
and use the narrator device. First we create a port to the device and attach 
the narrator_rb structure to it; this is accomplished by a call to CreatePort!) 
and a subsequent call to CreateExtlOf). Both of these functions are general 
purpose system calls that are used whenever it is necessary to interact with 
the Exec kernel's underlying message passing system. The next step is to 
initialize the wmes, our narrator_rb struct, to properly interact with the 
narrator device. Most importantly, we set the message.io_Comm.and field to 
CMD_WRITE, to indicate that we desire an output operation rather than 
input. This is a necessary prior step to the use of OpenDeviceO to set the 
process in motion. 

Once you have opened the narrator device, you are free to send command 
messages to it and wait for its activity; however, before you send a message, 
you must initialize it to the values on which you want it to operate. Foremost 
of these values is the string of phonemes that is to be pronounced; this goes 
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into the message.io _Data field. This field should be cast to an absolute 
address data type— APTR. The length of this field is put into message.io _ 
Length. These two fields, along with the message.io _Command field, are part 
of the standard message structure. The other fields that need to be set are 
peculiar to the narrator_rb structure itself. These are explained above, and 
the example contains typical values. 

Once you have translated a line of text, done the setup, and opened the 
device, you are ready to send an I/O request to the Narrator. In the example, 
we use the simplest call, DoIO(). This sends the command structure with its 
variables to the device, and then stops and waits for a reply. Once that reply 
has been obtained, we return to the main program and execute a call to 
CloseDevicef ), before stopping the program. As we have noted before, it 
very important to close unused resources with the Amiga; otherwise, you ma; 
run out of a most important resource— main memory. 

The example in Listing 8-3 is a modification of the previous program. 
This program is set up to deal with more than one line of input. The primary 
modification is the creation of a third function, set _to _talk( ), which handles 
all setup for the narrator device. This step is necessary, because we are going 
to send multiple messages to this device, but we need only open it once. Note 
that we call set _to _talk( ) outside the main program loop. 

Listing 8-3. Use of Set_to_talk( ) function to allow an 
unlimited number of spoken lines. Speech is produced using 
the translator library and narrator device. 

((define ERR 1 
((define SUCCESS 0 
((define REV 0 

((include <exec/types.h> 

((include <exec/exec . h> 

((include <exec/nodes .h> 

((include <exec/ U sts . h> 

((include <exec/memory .h> 

((include <exec/interrupts.h> 

((include <exec/ports . h> 

((include <exec/libraries.h> 

((include <exec/io.h> 

((include <exec/tasks . h> 

((include <exec/execbase.h> 

tfi nc lude <li brari es/trans lator. h> 

((include <devi ces/audio.h> 

((include <devi ces/narrator.h> 

((include <lattice/stdio.h> 

struct Library *Trans latorBase=NULL; 
extern struct Library *0penLi brary () ; 
struct MsgPort *WPort ,*RPort; 
extern struct IORequest *CreateExtIO() ; 
extern struct Library *0penLibraryO ; 
struct narrator_rb *wmes; 
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Listing 8-3. (cont.) 



struct mouth_rb *rmes; 

BYTE audChanMasks[]=-C3,5,10,12} ; 
ma i n () 



UBYTE in_string[80] ,out_string[300] ; 

if(set_to talkO==ERR) 
exit (FALSE) ; 

for(;;) { 

printf ("enter string "); 
gets(in_string); 

if ( !strcmp(in_string,"%halt")) 
break; 



lf(9e exU(FArs^ 



i f (talk_to_me(out_string)==ERR) 
exi t (FALSE) ; 



CloseDevice(wraes); 



get_phoneme(in, in len, out ,out len) 
UBYTE *in,*out; 
SHORT inlen.out len; 



ZA *A002A 



T 



TranslatorBase=(struct Library *) 

OpenLibrary ("translator. library", REV) ; 

i f (Trans latorBase==NULL) 
return(ERR) ; 

i f ((Trans late (in, in len, out, out len)) i=0) 
return(ERR) ; 

C loseLi brary (Trans latorBase); 
return(SUCCESS); 



talk_to me(speech) 
UBYTE *speech; 
{ 
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Listing 8-3. (cont.) 



wmes->message. io_Data=(APTR) speech ; 
wmes->message.io_Length=str I en (speech) ; 
wmes->ch_masks=audChanMasks; 
wmes->nm_masks=si zeof (audChanMasks) ; 



wmes->mouths=0; 

wmes->voLume=32; 

wmes->rate=20; 

wmes->sex=MALE; 

wmes->pitch=DEFPITCH; 



DoIO(wmes) ; 



set_to_talk() 
{ 

if ((UPort=(struct MsgPort *) CreatePort (0 ,0) ) ==NULL) 
return(ERR) ; 

if ((wmes=(struct narrator_rb *) 

CreateExtIO(WPort,si zeof (struct narrator_rb) ) )==NULL) 
return(ERR); 



wmes->message.io_Command=CMD_WRITE; 

if (OpenDev ice ("narrator. device", O.wmes.O) !=0) 
return(ERR); 

return(SUCCESS); 



.4 



w 
m 



One important flaw in the two previous examples is that they d<F, 
take full advantage of the multitasking capabilities of the Amiga. Whenever « 
message is sent to the narrator device, the current program goes into ajjf 
state until the message has been received and a reply sent. Since the dri" 
for this device is independent of the calling program, it would make 
sense to send the message and then continue processing. Earlier discuss 
of multitasking have shown that there are a number of ways to acconr 
this. Listings 8-4 and 8-5 illustrate a multitasking format commonly 
with the speech synthesis subsystem. 



322 



Chapter 8 



Listing 8-4. Multitasking format used with the speech 
synthesis subsystem. A single line is converted to phonemes, 
then spoken. 



tfdefine ERR 1 
fldefine SUCCESS 0 
#define REV 0 

^include <exec/types.h> 
^include <exec/exec . h> 
. ^include <exec/nodes.h> 
^include <exec/lists.h> 
^include <exec/memory . h> 
^include <exec/interrupts.h> 
^include <exec/ports.h> 
#include <exec/Ubran'es.h> 
^include <exec/io.h> 
#include <exec/tasks . h> 
^include <exec/execbase. h> 
^include <libraries/translator.h> 
^include <devices/audio.h> 
^include <devi ces/narrator.h> 
^include <Lattice/stdio.h> 

struct Library *Trans LatorBase=NULL; 
extern struct Library *0penLi brary O ; 
struct MsgPort *WPort , *RPort ; 
extern struct IORequest *CreateExt I0O ; 
extern struct Library *0penLibrary() ; 
struct narrator_rb *wmes; 
struct mouth_rb *rmes; 

BYTE audChanMasks □ ={3, 5, 10,1 2>; 

mainO 
{ 

UBYTE in_string[80] ,out_st ring [300]; 

printf ("enter string "); 
gets(in_string) ; 

if (get_phoneme(in_string,strlen(in string) .out string, 300) ==ERR) 
exi t ( FALSE) ; 

if(talk to me(out_string)==ERR) 
exit (FALSE) ; 

CloseDevice(wmes); 

> 

get_phoneme(in, inlen.out ,out Len) 
UBYTE *in,*out; 
SHORT inlen.out Len; 



£ * A H ° 
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Listing 8-4. (cont.) 



TranslatorBase=(struct Library *) 

OpenLibrary ("translator. Library", REV) ; 

if (TranslatorBase==NULL) 
return(ERR) ; 

if ( (Trans late(in, in len.out, out len)) !=0) 
return(ERR) ; 

CLoseLibrary(Translator8aS9 ^QIlM:AT J 

return(SUCCESS); 

ZERO 

..ik ..<„.«„> ZARAGOZA 

UBYTE *speech; 



if ((WPort=(struct MsgPort *)CreatePort(0,0))==NULL) 
return(ERR) ; 

if ((RPort=(struct MsgPort *) CreatePort (0,0) )==NULL) 
return(ERR) ; 

if ((wmes=(struct narrator_rb *) 

Create£xtIO(WPort,sizeof (struct narrator rb) ) )==NULL) 
return(ERR) ; 

if ((rmes=(struct mouth_rb *) 

CreateExtIO(RPort,sizeof (struct narrator rb)))==NULL) 
return(ERR); 



wmes->message. io_Command=CMD_URITE; 
wmes->message. io_Data= (APTR) speech; 
wmes->message. io_Length=st r ten (speech) ; 
wmes->ch_masks=audChanMasks; 
wmes->nm_masks=si zeof (audChanMasks) ; 



if (OpenDev ice ("narrator. device", O.wmes.O) !=0) 
return(ERR) ; 

wmes->mouths=0; 

wmes->volume=32; 

wmes->rate=20; 

wmes->sex=MALE; 

wmes->pitch=OEFPITCH; 
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Listing 8-4. (cont.) 



rmes->voi ce. message. io_Device=wmes->message. io Devi ce; 

rmes-> voice. message. io_Unit=wmes->message.io Unit; 

rmes->width=0; 

rmes->height=0; 

rmes->voi ce. message. io_Command=CMD_READ; 
rmes-> voice. message. io_Error=0; 

SendlO(wmes) ; 

while (rmes->voice. message. io Error!=ND_NoUrite) 
DoIO(rmes) ; 

return(SUCCESS); 

> 



Before delving headlong into a discussion of these two listings, we must 
explore another structure associated with the narrator device: 

struct mouth_rb { 

struct narrator rb voice; 
UBYTE width, 
height, 
shape, 
pad; 

>; 

This structure is used to send information back from the Narrator to the 
calling routine. Specifically, it returns two values, width and height, which 
can be used ko produce an animated picture of a mouth. The narrator device 
calculates these two variables based on the phoneme it is now speaking. If 
these values are to be used, the mouth field in the narrator_rb structure 
must be set to a value other than 0. 

Even if you are not interested in associating a screen image with the 
spoken word issuing from the computer, you can use the mouth _rb structure 
to set up a monitoring task that allows you to send messages to the Narrator, 
but not wait for their completion. This is illustrated in Listing 8-4. This 
program is similar to the earlier Listing 8-2; it accepts a single line as input, 
converts it to phonemes, and then speaks it. Here, however, we declare two 
associated structures: a narrator_rb and a mouth structure. To accommodate 
them, we open two ports: one to write to and one to read from. We open the 
device with the narrator_rb structure and then copy the message _io.Device 
and message _io. Unit to the mouth_rb structure. This insures that the two 
are linked during the I/O operations. 

Once initialization is complete, we access the Narrator via a SendlOf) 
command. This transmits our command message and then continues with the 
rest of the program. Meanwhile, a DoIOf) operation is performed using the 
mouth_rb structure. When the Narrator has finally finished speaking the 
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entire message, it sets the voice.message.Error field to ND_NoWrite These 
I/O operations are performed until this condition is met. Listing 8-5 also uses 
the SendlOJ) function and the dual structures, but in the context of a contin- 
uous loop in the main program. 

Listing 8-5. Multitasking format used with the speech synthesis 
subsystem. An unlimited number of lines can be spoke n. 

^define ERR 1 
tfdefine SUCCESS 0 
^define REV 0 

^include <exec/types.h> 
((include <exec/exec .h> 
((include <exec/nodes.h> 
((include <exec/lists.h> 
((include <exec/memory .h> 
^include <exec/interrupts.h> 
((include <exec/ports.h> 
/(include <exec/libraries.h> 
^include <exec/io.h> 
^include <exec/tasks.h> 
"include <exec/execbase.h> 
^include <libraries/translator.h> 
include <devi ces/audio.h> 
"include <devi ces/narrator.h> 
"include <lattice/stdio.h> 

struct Library *Trans latorBase=NULL; ' 

extern struct Library *OpenLi brary () • 

struct MsgPort *WPort . *RPort ; 

extern struct IORequest *CreateExtIO() ; 

extern struct Library *0penLibraryO • 

struct narrator rb *wmes; 

struct mouth_rb~*rmes; 

BYTE audChanMasks[]=<3,5,10,12>; 
mainO 



UBYTE in_string[80] ,out_st ri ng C300] ; 

if(set_to talk()==ERR) 
exit (FALSE); 

for(;;) { 
printf ("enter string "); 
gets(in_string) ; 

if (!strcmp(in string, "%%")) 
break; 



if(get_phoneme(in_string,strlen(in.string),out_string.300)==ERR 



m 
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Listing 8-5. (cont.) 



exi t (FALSE) ; 

if(talk to me(out_stn'ng)==ERR) 
exi t (FALSE) ; 

} 

CloseDevice(wmes) ; 

> 

get_phoneme(in, inlen.out ,out len) 
UBYTE *in,*out; 
SHORT inlen,outlen; 
< 

TranslatorBase=(struct Library *) 

OpenLi brary ("translator, library", REV); 

if (Trans latorBase==NULL) 
return(ERR) ; 

if ((Trans late (in, in len, out, out len)) !=0) 
return(ERR) ; 

CloseLi brary (Trans latorBase) ; 
return(SUCCESS); 

> ■ 

2 --AO. i 
.til t ::?s f"* 

UBYTE *ipeech; y . _ * * KJ 

wmes->message.io_Data=(APTR)speech; w A 

wmes->message. io_Length=str len (speech); 
wmes->ch_masks=audChanMasks; 
wmes->nm_masks=si zeof (audChanMasks) ; 



wmes->mouths=0; 

wmes->volume=32; 

umes->rate=20; 

wmes->sex=MALE; 

wmes->pitch=DEFPITCH; 



SendlO(wmes) ; 

while (rmes->voice. message. io_Error!=ND NoWrite) 
DoIO(rmes) ; 

> 
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Listing 8-5. (cont.) 



set_to_talk() 
{ 

if <(WPort=(struct MsgPort *) CreatePort (0,0) )==NULL) 
return(ERR) ; 

if <(RPort=(struct MsgPort *)CreatePort(0,0))==NULL) 
return(ERR) ; 

if ((wmes= (struct narrator_rb *) 

CreateExtIO(WPort,sizeof (struct narrator rb)))==NULL) 
return(ERR) ; 

if ( (rraes=(struct mouth_rb *) 

CreateExtIO(RPort,sizeof (struct narrator rb)))==NULL) 
return(ERR) ; 

wmes->message.io_Command=CMD_WRITE; 

i f (OpenDev ice ("narrator. device", 0,wmes,0) i=0) 
return(ERR) ; 

rmes->voi ce. message. io_Devi ce=wmes->message. i o_Devi ce; 
rmes->voice. message. io Uni t=wmes->message. io Unit- 
rmes->width=0; 
rmes->height=0; 

rmes->voi ce. message. io_Command=CMD_READ; 
rmes->voi ce. message. io_Error=0; 

return(SUCCESS) ; 



Experimenting with the Narrator 



Now that you understand the basic operation of the speech synthesis suijjH 
tem on the Amiga, it is important to also consider the effects of varying i" 
parameters that are sent to this device. Although a great deal can be T 
with just the basic operation— the speech, as it stands, is clear and 
understandable— slight modifications to the default values can provide^ 
more controlled performance. It is even possible to correct some of the t 
guities that are understandably found in this complicated set of pro 

Listing 8-6. Use of set_params() function to set the 
parame ters of speech. 

#define ERR 1 
fldefine SUCCESS 0 
^define REV 0 
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Listing 8-6. (cont.) 



^include <exec/types . h> 
^include <exec/exec . h> 
^include <exec/nodes . h> 
#include <exec/lists.h> 
^include <exec/memory.h> 
^include <exec/interrupts.h> 
^include <exec/ports.h> 
^include <exec/ I i brari es . h> 
^include <exec/io.h> 
flincLude <exec/tasks.h> 
^include <exec/execbase. h> 
^include <libraries/translator.h> 
ffincLude <devices/audio.h> 
^include <devices/narrator.h> 
^include <latti ce/stdio.h> 

struct Library *TranslatorBase=NULL- 

extern struct Library *OpenLibrary () • 

struct MsgPort *WPort,*RPort; 

extern struct IORequest *CreateExtIO() • 

extern struct Library *OpenLibrary () ■ ' 

struct narrator_rb *wmes; 

struct mouth_rb~*rmes; 

BYTE audChanMasksn=<3,5,10,12>; 
mainO 



nllll in - str - in 9[80],out.string[300]; ^BMAT 
UWORD voLume=55,rate=20; r» _ * 

& 111 ia r> 

if (set_to_talk()==ERR) . 



•xi t (FALSE) ; A R A G O Z A 

for(;;) { 

printf ("enter string "); 
gets(in_string) ; 

if (Istrcmpd'n stri ng, "%ha It") ) 
break; 

if ( !strcmp(in_string,"%set")) { 
set_parans(8volume,Srate) ; 
conti nue; 

lf i!?!^^ Cout - stri ' n9 ' volume ' rate)== ERR> 

ex l t (FALSE) ; 

> 
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Listing 8-6. (cont.) 



C LoseDevi ce(wmes) ; 



get phoneme(i n, i n ten, out ,out Len) 
U8YTE *in,*out; 
SHORT inlen.outlen; 
{ 

Trans LatorBase=(struct Library *) 

Open Library ("translator. Library", REV) 

if (Trans latorBase==NULL) 
return(ERR) ; 

if ( (Trans Lated'n, in len, out, out Len)) !=0) 
return(ERR) ; 

Close Li brary (Trans LatorBase) ; 

return(SUCCESS); 

> 

talk to me(speech,vol,rate) 
UBYTE *speech; 
UUORD vol, rate; 
{ 

wmes->message. io_Data=(APTR) speech; 
wmes->message. io_Length=str I en (speech) ; 
wmes->ch_masks=audChanMasks; 
wmes->nni_masks=si zeof (audChanMasks) ; 

wmes->mouths=0; 

wmes->volume=vol; 

wmes->rate=rate; 

wmes->sex=MALE; 

wmes->pitch=DEFPITCH; 

SendlO(wmes) ; 

whi le (rraes->voi ce. message. i o_Error ! =ND_NoWri te) 
DoIO(rmes) ; 

> 

set to talkO 
< 

if ((WPort=(struct MsgPort *) CreatePort (0,0) )==NULL) 
return(ERR) ; 

if ((RPort=(struct MsgPort *)CreatePort(0,0))==NULL) 
return(ERR) ; 
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Listing 8-6. (cont.) 



i f ((wmes=(struct narrator_rb *) 

C reateExt 10 (WPort, si zeof (struct narrator_rb) ) )==NULL) 
return(ERR) ; 

i f ( (rmes=(struct mouth_rb *) 

C reateExt 10 (RPort, si zeof (struct narrator_rb) ) )==NULL) 
return(ERR) ; 

wmes->message. io_Command=CMD_WRITE; 

if (OpenDev ice ("narrator. device", 0,wmes,0) !=0) 
return(ERR) ; 

rmes->voi ce. message. io_Device=wnies->message. io Devi ce; 
rmes->voi ce .message . i o_Uni t=wmes->message . i o Uni t ; 
rmes->width=0; 
rmes->height=0; 

rmes->voi ce. message. i o_Command=CMD_READ; 
rmes->voi ce. message. io_Error=0; 

return(SUCCESS) ; 

} 

set_params (vo I , rate) 
UWORD *vol,*rate; 
{ 

int x,y; 

printf ("volume==>") ; 
scanf ("%d",Sx); 

printf ("rate ==>"); 
scanf ("%d",8y) ; 

*vol=(UW0RD)x; 
*rate=(UWORD)y; 



o 



Listing 8-6 contains a prototype program that allows us to enter values 
for the volume and rate fields of the narrator_rb structure. It is similar in 
design to the example in Listing 8-7, but we have added a fourth function, set 
-paramsi). This new function prompts the user to provide values for these 
fields, and then passes them back to the main part of the program. Talk_to_ 
me( ) has also been modified to accept these parameters. This is a very simple 
example. There are no default values for these fields; they must be set by the 
user before the loop in main() begins. Set _Params( ) is the first function call 
in the program. Note, too, that the assignments to the fields in the narrator _ 
rb structure are done after the OpenDevicef) call but before any I/O function 
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is accessed. Although we haven't provided code for error checking on entered 
values, the example illustrates a way to better understand the results of 
varying the Narrator values. 

Listing 8-7. Addition of pitch, mode and sex values to 
set_params() function. This expands the range 
of speech parameters. 



fldefine ERR 1 
#define SUCCESS 0 
#define REV 0 



^include <exec/types . h> 
^include <exec/exec.h> 
^include <exec/nodes.h> 
^include <exec/lists.h> 
^include <exec/memory .h> 
^include <exec/interrupts.h> 
^include <exec/ports.h> 
^include <exec/libraries.h> 
^include <exec/io.h> 
Jh'nclude <exec/tasks . h> 
^include <exec/execbase. h> 
^include <libraries/transtator.h> 
Jh'nclude <devices/audio.h> 
^include <devices/narrator.h> 
^include <lattice/stdio.h> 



struct Library *Trans LatorBase=NULL; 

extern struct Library *OpenLi brary () ; 

struct MsgPort *WPort,*RPort; 

extern struct IORequest *CreateExt IOO ; 

extern struct Library *0penLibraryO ; 

struct narrator_rb *wmes; 

struct raouth_rb *rmes; 

BYTE audChanMasks[]=<3,5,10,12>; 
mainO 



UBYTE i n_st ring [80], out_st ring [300]; 

UUORD volume=55,rate=207pitch=DEFPITCH,mode=DEFMODE, 



sex= 



if(set to talk()==ERR) 
exit (FALSE); 

for<;;) { 

printf ("enter string "); 
gets(in_string) ; 

if (!strcmp(in_string,"%halt">) 
break; 



■ gH 



if (!strcmp(in_string,"%set")) i 



13a 
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Listing 8-7. (cont.) 



con^nue- S(&VOLUme ' Srate ' Spi ' tCh ' 8m0de ' 8sex) '- 

} 



' ^ex?t (FALSE) ;° Ut_Strl V0 ' -Ume ' rat e,pi t ch , mode, sex)==ERR) 



> 

CloseDevice(wmes); 

> 

g e t phoneme ( i n , i n I en , out , out I en) 
UBYTE *in,*out; 
SHORT inlen.outlen; 

TranslatorBase=(struct Library *) 

OpenLi brary ("translator. L i brary", REV); 

i f (Trans L at orBase==NULL) 
return(ERR); 

if ((Trans I ate (in, in ten, out, outlen)) i=0) 
return(ERR); 

CloseLi brary (Trans latorBase) ; 

return(SUCCESS); 

> 

UWORD vol, rate, pitch, mode, sex; 

wmes->message. io_Data=(APTR) speech- 
wmes->message.io_Length=strlen(speech)- 
wmes->ch_masks=audChanMasks; 
wmes->nm_masks=sizeof (audChanMasks) ; 

wmes->mouths=0; F O R I^-^lIC 

wmes->volume=vol; 

wmes->rate=rate; ^ TpJ ¥1 

wmes->sex=sex; 

wm^s-^Sode'mlder'' 
SendlO(wmes) ; 
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Listing 8-7. (cont.) 



> wh ii!o^ r :i s s n voice - fflessa9e - io - Error!=ND - Now ^t^ 



set_to talkO 
{ 



^r'SSlfr" MS9P ° rt * )C -tePo r t(0.0))==NULL) 

^^urnCERR)^" MS9P ° rt *> Cr -tePort (0.0) )==NULL) 

if ((wmes=(stmct narrator rb *) 

r^turnl^?;^"' 51 -" 0 ^^-^ -rator.rb) ) ) ==NULL) 

if ((rmes=(struct mouth rb *) 

^n(^?; RP ° rt ' S1 ' ie0f(StruCt narrator„rb))) ==NU LU 

wmes->message.io_Command=CMD_WRITE; 

i "K! £ , iR';'' narr ""- <i " i « , '' o -»«.<'''--o> 

rmes->height=0; 

r!frs VO - Ce - meSSa9e - io - Comman d=CMD READ ■ 
rn.es->voi ce. message. io_Error=0; " 

return(SUCCESS); 



> 

uSoRD a I!nf c *° L : rate - P1 ' tch ' mode . se *> 

UWORD *vol.*rate, -pitch, *mode,* se x; 

1nt x,y,z; 
char chC80]; 

printf ("voLume==>") • 
scanf ("%d",&x); 

printf ("rate ==>")• 
scanf ("%d", &y); 

*vol=(UW0RD)x; 

*rate= (UWORD) (MINRATE+y); 

printf ("pitch ==>")■ 
scanf ("Xd" Sz); 

*pitch=z; 
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Listing 8-7. (cont.) 



Printf ("mode ==>■-). 
scanf ("%s",ch); 

if(!strcmp(ch, "inflected")) 

*mode=NATURALF0- 
if(!strcmp(ch, "monotone")) 

*mode=ROBOTICFO; 

printf ("sex ==>»). 
scanfC'»% S ",ch>; 

if C!strcmp(ch,"maLe")) 
*sex=MALE; 

ifC!strcmp(ch # "femate")) 
*sex=FEMALE; 

> 



«»-to Wf> functions. Thi 5gi » 6 , , *ITf t0 b « h "» s.'-po™™,, „ d ' 
tocvrloat when prodncingTo' ,, ~ 1 ^ with wlS 
add, more complexity. I„ thi, \S£± l'*?™™'*' in Listing M 

s rrr * * ~ ^^i^a^ 

A , £ thet ^ as to c . the ^ „ 

• Support for default values It i. „„ i 

for each parameter if to «ter values 

^iXK^^ WWch «» be "-d 'directly to pl ay with th 
*e capahiht, of speet^her E£S££F" 



^define ERR 1 
fdefine SUCCESS 0 
define REV 0 

Jinclude <exec/types.h> 
I " c ude <exec/exec.h> 
#]nc ude <exec/nodes.h> 
J nc lud e <exec/lists.h> 
#inc ude <exec/memory. h > 
include <exec/interrupts.h> 
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Listing 8-8. (cont.) 



^include <exec/ports . h> 
^include <exec/libraries.h> 
^include <exec/io.h> 
^include <exec/tasks.h> 
^include <exec/execbase.h> 
^include <Libraries/translator h> 
#include <devi ces/audio.h> 
^include <devi ces/narrator . h> 
^include <Lattice/stdio.h> 

struct Library *Trans latorBase=NULL • 

extern struct Library *OpenLibrary ()' • 

struct MsgPort *WPort,*RPorf 

extern struct IORequest *CreateExtIO() • 

extern struct Library *OpenLibrary ) ' 

struct narrator rb *wrnes: 

struct mouth_rb *rmes; 

BYTE audChanMasks[]=O,5,10,12>; 
ma i n ( ) 

uSoro in 7 Stri "| C80] .° u t-String[300]; 

UW0RD M&M^ wrf «.^™00I. 

if(set_to talk()==ERR) 
ex i t (FALSE) ; 

for(;;) { 

printf ("enter string ") • 
gets(in_string); 

if (!strcmp(in_string,"Zhalt")) 
break; 



f * 



i f ( ! strcmpd'n string, "Xset")) { 

c"n^e amSC8VOLUme ' 8rate ' 8pitCh ' &mode '^^.S^eq); 

> 



^^(FaTsI)'^ 
> 

CloseDevice(wmes) ; 

> c' 
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SHORT inlen.outlen; 

Trans latorBa^o-/',.*. 

° ase-(struct Librar Y *) 

OpenLibrary(.. translator 

return (ERR); LU 

CloseLibrary(TranstatorBase); 
return(SUCCESS); 

> 

{ ' ate ' pitch .™ode,sex,freq; 

-"—--sks-sizeofcSanMasks,; ^ 

Essay'' ze Ro 

wmes->pitch=pitch- 7 A n 

wmes->mode= mo de; AR AG02A 
«n>es-> S ampfreq=fp eq ; ** 

SendlO(wmes); 

while (rmes->voicp m£ >e 
} DoIO(r me s); Ce - meSSa 9 e -'0-Error 1=ND _ NoWri . te) 

set_to_tatk() 

if ((WPort = (<5tri,^-t. u ~ 

return (ERR) ; MsgPort * ) CreatePort(0,0))= =NULL) 

, ^ffii) t r ,et MS3POrt *^-atePort(0.0)) ==NUU) 

if ((wmes=(strnr*- „ 

struct narrator_rb *) 
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Listing 8-8. (cont.) 



^^n(ERR?; (WP0rt ' Si2e0f(st -« narrator_rb))) ==NULL ) 

if Urmes= (struct mouth rb *) 

net e u a r n(ER;?; RPOrt ' Siie0f(st - ct -rrator.rb) , )==NULL) 

wmes->message.io_Command=CMD_WRiTE; 

rmes->width=0; e " 1 °- Uni ^es-^essage. io_Unit; 
rmes->height=6; 

rrnes->voice. message. io_Command=CMD READ- 
rmes->voi ce. message. io:Error=0;' 

^return(SUCCESS); 

t «i, ral; e.*P'tch,*mode,*sex,*freq; 

int x; 

char chC80]; 

printf ("volume==>") - 
gets(ch); 
if (ch[0]=='\0>) 

t 

else { 
x=atoi (ch); 
*vol=x; 

> 

printf ("rate ==>")- 
gets(ch); 
if (ch[0]=='\0') 

§ 

else -C 
x=atoi (ch); 
*rate=x; 

> 

printf ("pitch ==>••)■ 
gets(ch); 
if (ch[0]=='\0') 

else { 
x=atoi (ch); 
*pitch=x; 

> 



Listing 8-8. (cont.) 



P r intf(" mode -_»„, 
gets(ch); 
'f(ch[03=='\0') 

9 

else 1 ' f ( | strcmp(ch "infi * 

* m nH rC D mp(ch ' ,,mo notone")) 
*mode=ROBOTICF0; 

Printf ("sex ==>1 
gets(ch); J ' 
if (ch[0J=='\ 0 .) 

eIse if ^strc«p(ch... male ,. )) 
Plc» ■ * se *=MALE; 

" lf ^S---,) 

if(ch[ 0 ] == .\ 01) H o 

else £ * ^ ft ^ 

x =atoi(ch); ° ^ 4 

*freq=x; 

> 



As mentioned earlier ,> • 1 

S* Addition „, ^ . 



^define ERR 1 
define SUCCESS 0 
"define REV 0 

"include <exe c/ ^° ry - h> 

exec/ ln terrupts.h> 



Listing 8-9. (cont.) 



^include <exec/ports . h> 
^include <exec/libraries.h> 
^include <exec/io.h> 
^include <exec/tasks.h> 
^include <exec/execbase.h> 
^include <libraries/translator.h> 
^include <devices/audio.h> 
^include <devi ces/narrator.h> 
^include <lattice/stdio.h> 



struct Library *Trans latorBase=NULL; 

extern struct Library *OpenLibrary () • 

struct MsgPort *WPort ,*RPort; 

extern struct IORequest *CreateExtI0O ■ 

extern struct Library *OpenLibrary () • ' 

struct narrator_rb *wmes; 

struct mouth_rb *rmes; 

BYTE audChanMasks[]={3,5,10,12}; 

mainO 
{ 



UBYTE in_string[80],out string[300] ; 

UWORD volume=55,rate=20,pitch=OEFPITCH,mode=OEFMODE 
sex=OEFSEX,freq=DEFFREQ; otrnODE, 



if (set_to_talk()==ERR) 
exit (FALSE); 

for(;;) { 

printf ("enter string ">; 
gets(in_string) ; 

if ( !strcmp(in_string,"Xhalt")) 
break; 



if ( ! strcmp(in_string, "Xset")) { 

set.params (Svolume, irate, Spi ten, Smode.&sex.Sf re 
continue; 




if ( IstrcmpO'n st ri ng,"%di reef) ) { 
printf ("»") ; 

^gets(out_string) ; 
else 

if(get_phoneme(in_string,strLen(in string), out stringW" 
exit (FALSE) ; " ' , , 
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Listing 8-9. ( con t.) 



if(talk_to_me(out strinn , ' 

CloseDevice(wmes); 

> 

. ulrf^K^r-^n.out.outUn) 
J«ORT inlen^len; 

TrWWl «""«- (struct Library 

if(Translator8as -----a nSt a to , libraryl , REv); 

return (ERR) ; NULU 

'ft (Trans late (in t~i 

r eturn(ERR); ' nten ' Out 'Outlen)) 1= 0) 

CloseLibrarydransUtorSase); 
return (SUCCESS); 

> 

< VOt ' ra ^.p,tch, ra ode. seX/freq; 

: -:>I:f^^]^f S APTR)spee Ch ; 

n^asks- s , zeof(audChanHasks) _ 
w mes-> mou ths=0- 

wmes->sex=sex- »■» — - "* 

wn.es-> pi - tch ; 

w«es ->mode= mo P de; h ' 
Wmes - >sa -"Pfreq=f req; 

Ser >dIO(wmes); 



z E H o 

2AR AGOZA 



Set -to_tal k () 
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Listing 8-9. (cont.) 



if C(WPort-(struct MsgPort *) CreatePort (0, 0) )==NULL) 

if ((RPort=(struct MsgPort *)CreatePort(0,0))==NULL) 
return(ERR) ; 

if ((wmes= (struct narrator rb *) 

CreateExtIO(WPort,sizeof(struct narrator rb)))==NULL) 
return(ERR); - ULU 

if ((rmes= (struct mouth rb *) 

CreateExtIO(RPort,siieof(struct narrator rb)))==NULL) 
return(ERR); 

wmes->message.io_Command=CMD_WRlTE; 

if (OpenDeviceC'narrator. device", O.wmes.O) i=0) 
return(ERR) ; 

™es->voice. message. io_Device=wmes->message.io Device- 
rmes->height=0; 

rmes->voice. message. io Command=CMD READ- 
rmes-> voice. message. io_Error=0; 

return(SUCCESS) ; 



set params (vol, rate. pitch, mode, sex, freq) 
UWORD *voL,*rate,*pitch,*mode,*sex,*freq; 
int x; 

char ch[80]; 



printf ("volume==>") ; 

gets(ch); 

if (ch[0]=='\0') 

else { 
x=atoi (ch) ; 
*vol=x; 

> 




% B 



G OX A 



printf ("rate ==>"); 

gets(ch) ; 

if (ch[0]=='\0') 



else { 
x=atoi (ch) ; 
*rate=x; 

> 
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Listing 8-9. (cont.) 



P""ntf ("pitch „>„,. 
3ets(ch); 
if (ch[0]==>\o>) 

0 

else i 
x=atoi (ch); 
^*pitch=x; 

P r intf (" mode ==>•■). 
gets(ch); 
ff(chC03=='\0'j 

. ko *mode=NATURALFO; " 

'^r^^^'^-tone")) 
*mode=ROBOTICF0; 

printf ("sex ==>.■>. 

9ets(ch); 

if (chCO]=='\o-) 

els e ''^'strcmp^h.-male")) 
*sex=MALE; 

if (ch[0]=='\o>) 
# 

else { 

x=atoi (ch); 
*freq= X ; 

> 



4n)o6«* frnJ ? re stan dard alphabetical * specification of any 
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Table 8-1. Some common Arpabet symbols. 



ft 

^ 0 



N 
O 
O 



Sound 


• Symbol 


Example 


A 


AE 


HAT 




AO 


BALK 




EY 


PAID 


B 


B 


BACK 


C 


K 


CARL 




CH 


CHOICE 


D 


D 


DIG 


E 


IY 


MEET 




EH 


PET 


F 


F 


FORT 


G 


G 


GOOD 


H 


/H 


HOLY 


I 


ER 


DIRTY 




IH 


HIT 




AY 


PIE 


J 


J 


JOIN 


K 


K 


KEEP 


L 


L 


LOW 


M 


M 


MICE 


N 


N 


NICE 




NX 


PING 


r 0 


AA 


POT 




UH 


LOOK 




OH 


HORDE 




AX 


TOUT 




IX 


SOLID 




OY 


TOIL 




OW 


KNOW . 




AW 


TOWER 


P 


P 


PET 


Q 


K 


QUIET 


R 


R 


READ 


S 


S 


SIT 




SH 


SHOOT 


T 


T 


TIE 




TH 


THING 




DH 


THE 


U 


AH 


BUNDLE 




UW 


POOL 


V 


V 


VOTE 


w 


w 


WASH 


X 


IC 


YECCH 


Y 


Y 


YELP 


Z 


Z 


ZEAL 




ZH 


MEASURE 



Vowels have two qualities that can also be specified in the pho 
alphabet: stress and intonation. In any given English word, some 
are stressed; others are not. You indicate this stress to the NarraWgg 
placing a digit between 1 and 9 immediately after a vowel in the*"!; 
syllable. The digit serves a dual purpose; it also specifies the inton 

■ 
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that vowel. There : are basically three kinds of intonation available: rising, flat 

SJSS ) G aV3ikble giVe US Varyifl e de S rees of these^iee 

Intonation values are shown in Figure 8-1. Finally, the narrator device 

7so^ c : t 7zi:°r oD r ctuation marks - These 

jUso indicate intonation values or pauses, of various length, between 
individual utterances. The recognizable punctuation marks and their vaTes 
are summarized in Figure 8-2. values 

Figure 8-1. Some intonation values 



articles 




Figure 8-2. Uses of common punctuation marks 



»■ Ends sentence or line 
•» Sets off a clause 

*■ Sets information for a question 

•* Sets off a phrase 

( ) *■ Sets off a noun phrase 
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Directly passing phonetic strings to the narrator device opens up new 
areas for speech experimentation: 

1. You can try to improve the pronunciation of special words peculiar to I 
your application. 

2. You can save the overhead of the translator library, if you just have a 1 
few words to say. I 

3. You can even experiment with foreign languages. 

However, keep in mind that for general purpose speech synthesis, it is stU 
more efficient to use the translator library and the narrator device together. : 



Summary 



In this chapter we have explored the Amiga's speech synthesis capability 1 
have seen how this capability is split across two separate subsystems: 1 

• The translator library 

• The narrator device 

Each one of these can function independently of the other. 

In many important respects, the speech synthesis subsystem is no moi 
exotic than more traditional devices, such as printers and display screen 
that are found on most computers. Access on the Amiga is obtained throug 
the message system that connects all devices defined on the Amiga. Furthe 
more, this message system allows you to run the narrator device in a ml 
titasking mode; this makes it even easier to integrate with the Amiga's otht 
features. 



1^ lS> \° 



o 
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FORMAT 
% E K O 

ZARAGOX A 



• The directory system 

• Traditional file rea rf anA 

Tie File Management System 

« directory that ™° 'f e ? dudM "» "°«on of a mf ' l data c ™ <» 

a»t alw you t„ ,™h ™J * MMS ri « h «- Alao neeSd „ ™J>«'»>t puan,. 
The fiClS^ ( Wri " data «° ■ '*> gt ' eVel ™ a « 

• Keeps track nf i . It; also: 

- — £E STa^t * - -* - - . r,a cao 
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• Notes the size of the file and the location of its extensions 

• Recognizes the type of file, and distinguishes between files and 
directories . 

Most of this information is available through one of the specialized Ami- 
gaDOS system calls. 

The standard TTY-style interface is also maintained by the file manage- 
ment system. The display screen, the keyboard and the printer are all treated as 
disk files even though the executive kernel recognizes them as different devices 
Additionally, the serial and parallel ports are also represented as file types 
AmigaDOS has a number of functions that support input and output from 
devices. Figure 9-1 lists the device files configured in a typical Amiga system. 

Figure 9-1. Device file identifiers 



NIL: 



<>=J>PAR: 

CON:<J=z£> 



<J=£>SER 



PRT 





RAW: 




The system functions that we will be dealing with in this chapter 
part of AmigaDOS. Just as with the multiprocessing examples in Chaptes 
these have been compiled using the initalization file AStartUp.obj and 
library amiga.lib, rather than the more common LStartUp.obj and I 
is necessary because the standard C library— found in Iclib— cont«u 
tions that have the same name as the AmigaDOS system calls; this lit 
will take precedence if it is linked first. A complete explanation for t 
found in Chapter 2. The necessary declarations are found in librarie 
and libraries/dosextens.h. 



The Notion of a File 



m 



its: 
tedn 



Most programmers have a rough idea of what constitutes a file. At i 
mum, it can be defined as a named location on an external storage ml 
usually some kind of disk— where values can be placed and later retu 7 
You can distinguish between a variable in memory and a disk file in a num 
ol ways, not the least of which is the ephemeral nature of the firs" ' 
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J ong-lasting qualities of the 
st ™« FileHandle t 



struct FileHandle t 

struct Msg ' , . 

»*niet MsgPort HM" 1 *'" 

struct MsgPort w,- P ° rt - 

LONG 3 * * f h.Ty pe; 



>: 

where 



■rtQlP> 

f Mrg2; % A ° A 



N °™ of the field, „ thl , „, f ° ,M " lie ^ 

Almost as importer • 1 * functlon s- Process, it ls Used to 

str <Jct Fi teLock f follows: 



LONG *LUnk; 

U Key, 

ffuct M Sg p ort I! 7 A " e f s ; 

>; f LVolun.e; 
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where 

fl_Link points to the next file lock on the linked list, 
fl_Key is the number of the disk block. 
fl_ Access contains the access mode. 
fl_Task indicates the port of the handler task. 
fl_ Volume points to the device list. 



Practical File I/O 



o 



nerlntrf V 8 , ^ * ffle is the most basic 0 P er ^ion that you can 

\ ' 6Ver ' DeVer USe the system Actions built in to the opera£ 

mg ystem environment, but are content with whatever facility is offered in 
the language that they have chosen to implement their aonlicatton T™ 
contexts this can be a mistake. Nothing works as ^Jf£S^±K 

^STsoL a eft n ' a system caU is often £ 

ir;~d f i e d z^™** language may be awkward - a 

din b!low C fCf ra TT g l3ngUage Pr0VideS 3 g °° d mu stration of the need to 
i below the level of programming language to the underlying software 

SS^SZf SfSf 6 ? c i s defhied 111 terms of a — H f 52S 

uasa type called b ILE. This structure contains information about the file 

SHSJSJP P r°f i0n ° f ^ POinter in the me - - d a buft to hold 
data from the file. The C functions that manipulate a file work through this 

£ta£ FlST^T ° f ^ b ? ferin ^^ed most of the mformattn 
neldm the FILE variable-is redundant. It is already available as Dart of the 

^70^^ h6ader FILE add3 » ~a5 1 

IT! i ° V ? F rhead t0 the P«>fc™ (Figure 9-2). This redundancy may not '4 

SSL? Pr0gramS ' ^ - number^SSl 

Figure 9-2. The redundancy of the C FILE structure 



Track Disk Device 



FILE 










buffer 






1 



application buffer 
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operating system environments, these functions fre them sXfs svstemST 
button most, they are not. Lattice C offers two levels 

1. Buffered I/O, whether formatted or not 
. 2. A set of low-level, stream-oriented statements 

E^wS thtsTurieMi 6 ; 3 ' ^ ? ^ n ° ***** 

SSJSt ' maDy appbcations AmigaDOS is an attractive 

Before you can do anything to a file, you must negotiate with the ooerat 
mg system and convince it to give you access to it. This E SmpiSS t 
the Openf) command. This function has the format: accon >piished by 

f i I e_hand I e=Open (f i L e_name .mode) ; 
where 

file_handle is a variable of type struct FileHandle. This identifies the 
file m subsequent commands; 0 indicates a failure to open Z 'file 

^n: namC It a , C . haracter strin S th ^t contains the file name as it 
appears in the directory. "* 

mode is the access mode being requested. 
Mode may be one of two values: 
MODE _ OLDFILE opens an existing file. 
MODE_NEWFILE specifies a new file. 
In both cases, the file is open for reading and writing 

, 2? e QP«^ system call can be used to open certain devices as well as 

f_handle=Open(-CON:0/0/200/150/Window",MODE_OLDFILE) 
This opens a new console window with the specified parameters 
over ^^^^^d using the file, it is necessary to relinquish control 
over it. This is easdy accomplished by calling: control 

CloseCf i le_handle) ; 

Soufcau^ Ooln T iabI nn« tyPe StrUCt F ^^, initialized by a 
previous call to OpenfJ. AmigaDOS is not civilized enough to clean ud after 

X J?" " a l mech ™ for automatically closing £; „s 
explicitly or risk running out of resources. This is a particul^^portant 
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matter with a multiprocessing system, where a resource that you forget to 
close becomes unavailable to a simultaneously executing process. This can 
even lead to a deadlock situation, where both processes come to a halt be- 
cause of contention over resources. 

Finally, we come to the statement that enables transfer of data from 
disk into memory. Recall that AmigaDOS treats a file as a stream of bytes— 
almost as an infinitely long character string. This architecture is reflected in 
the input function call: 

byte_count=Read(f i le_handle,buf fer,buf_si ze) 
where 

byte _ count is the number of bytes actually transferred, 
file —handle is the file identifier. 

buffer is a pointer to a hunk of contiguous characters, 
buf _size is the number of locations in the buffer. 

Both byte_count and buf_size are integer values, but remember that fd 
AmigaDOS this means thirty-two bits. When executed, ReadO attempts 
transfer the next buf size bytes in the buffer array. If it succeeds, byte^ 
count is equal to buf size. If there are fewer bytes left then have been 
requested, these are transferred and byte_count is set accordingly. A value of 

0 in ;his variable indicates that the end of the file has been reached. A value of 

01 shows an error condition. 

The output function is complementary to the input: 

byte_count=Write(f i le_hand Le,buf fer,buf_size) . 

Here, the parameters are the same as those for the Readf ) function. You in- 
fill the buffer with the characters or bytes that you want transferred to, 
file. The parameter bufsize indicates how many of these are to be sent 
WriteO returns the number of bytes actually placed on the file; in 
situations, byte_count and buf size should be equal. A —1 value 
variable indicates an error condition. rf^i. 

These four system calls are illustrated in Listing 9-1. This pro. 
copies the contents of a file to a window on the display screen. First we a 
the file name through the command line arguments. Once we have this n« 
a call to Open<) with a mode of MODE _OLDFILE prepares this file 
reading. If the file cannot be opened, we unceremoniously stop execution wi 
an Exiti) call. We perform a similar service for the new window that will 
our display medium. 

Once we have our two files open, we prepare a buffer. Instead 
simpler process of declaring a large array of characters, we use Alio* 
dynamically allocate this space. This has the felicitous property of alloca^ 
this buffer on 32-bit boundaries— something that AmigaDOS likes a „ 
deal. A simple "do" loop empties the file into the buffer, and the buffei 
the window. This loop continues until the variable len indicates that 
of the "form" file has been reached. 
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ttinc lude 
#inc lude 
#inc Lude 
#\ nc Lude 
#inc Lude 
/'include 
#inc lude 
"include 
"include 
"include 



Listing 9-1. Use of Open(), Close() ( ReadO, and WriteO 
Program accepts a file, opens a window, and dispLy L 
contents of the file in that window 

<exec/types.h> 
<exec/nodes.h> 
<exec/lists.h> 
<exec/libraries.h> 
<exec/ports.h> 

<exec/interrupts.h> 
<exec/io.h> 

<exec/memory.h> 
<libran'es/dos.h> 
<libran'es/dosextens.h> 



"define BUFF_SIZE 256 

extern struct FileHandle *0penO, 

main(argc,argv) 
int argc; 
char *argv[] ; 

struct FileHandle *fp,* SD - 
char *buffer; ' 
int len; 



1 lf Ex ft O ^ ^ V C 1 ] ' M0DE - OLDF 1 LE > > ==0) 



ifccs P =o pen( ..^ 

buffer=(char *)A1 locMem(BUFF_SIZE,HEMF_CHIP|HEMF_CLEAR); 



do { 

len=Read(fp, buffer, BUFF SIZE)- 
Wnte(sp, buffer, Len); " 

whi le(len!=0); 

FreeMem(buffer,BUFF_SIZE); 

CLose(sp) ; 
CloseCfp); 



toiJ^^ of memory via a call 

- on a single ^5^^ 
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undiscussed system call in this program-.ExitfV-but its operaton is 
straightforward and obvious. 

AmigaDOS supplies one additional system function related to file input 
and output: 

oLd=Seek(f i le_handle,new,from_mode) 

This moves the file cursor to a position specified by the parameters. Old and 
new are both integers. Old marks the current position of the file cursor. New 
specifies the new position as an offset from one of three positions: 

1. The beginning of the file 

2. The current position of the cursor 

3. The end of the file 

The active position is a function of the value found in the from_mode param- 
eter: OFFSET_BEGINNING, OFFSET_CURRENT, or OFFSET_END. 
This system function can be used in conjunction with Readf) and Write!) to 
update a file. 



File Maintenance Functions 

Reading and writing are not the only things you do to a file; you may need to 
manipulate it in other ways. AmigaDOS offers system services to support a 
variety of those needs. 

The Rename! ) function allows you to change the name of an existing file; 
it has the general form: 

boo lean=Rename (o Id , new) 

where 

boolean is the return value— either 1 (true) or 0 (false), 
old is a character string containing the current name of the file, 
new is also a character string, this one with the new name. 

If the name mentioned in new is of an existing file, the call will fail. Both old 
and new can be hilly qualified file names; it is possible to move a file from one 
directory to another by taking advantage of this capability. It is not, how- 
ever, possible to move a file from one volume to another. 

Listing 9-2. Use of RenameO. Program accepts two file names 
and changes the name of the file from the firs t to the second. 

"include <exec/types.h> 

"include <exec/nodes.h> 

"include <exec/Usts.h> 

"include <exec/Libraries.h> 

"include <exec/ports.h> 

"include <exec/interrupts.h> 
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Listing 9-2. (cont.) 



"include <exec/io.h> 
"include <exec/memory.h> 
"include <libraries/dos.h> 
"include <libraries/dosextens.h> 



extern struct FileHandle *0penO; 



main(argc,argv) 
int argc; 
char *argv£l; 

struct FileHandle *sp; 

if<<sp--Open(..CON: 1 0/10/300/150/W l ndow..,MODE_OLDFI LE )) ==0 ) 



WriteCsp, "Renaming Fi les ",20); 

if ((Rename (argvd] ,argv 12])) ==0) { 
WnteCsp. "Files Not Renamed", 20) ; 
Close(sp); ' 
^ExitO; 

Close(sp) ; 



z^ G0Z 



accent two Il. n P T \T Ple but typicaI use of ^namef). Here we 
accept two file names through the command line arguments-an old file nanle 

mLj^Hlt ^ ° De - We abo °P en a new ^ow to chsplay a hWe 
message that the renaming is taking dW Tf * •, ""^J d ucue 

fact and exit the program g * ' " ^ WG re P 0rt this 

You dt?h ther .^ P0rtant - if Mastic-task is to remove a file from the disk 
You do this with a system call: 

boolean=DeleteFi le(f i le_name) 

file ™T' b0 ° l T " 3 r6tUrn V3lue ******** the success of the action and 
?nt 7vT 18 V haraCter String c ° nt aining the name of the file to be removTd 
This system function removes either an ordinary file or a directorv rt 
directory must be empty before it can be removed LiB^ ^SSs^e 

Sl^m'r Again ' We a messa ^ while the deleton • 

taking place; if it fails, we exit the program with an error message. 

Listing 9-3 Use of DeleteFile< ). Program accepts a file name 
m the command line and removes it from the disk. 



"include <exec/types.h> 
"include <exec/nodes . h> 
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Listing 9-3. (cont.) 



#iiclude <exec/lists.h> 
^include <exec /libra ries.h> 
#iiclude <exec/ports.h> 
^include <exec/interrupts.h> 
^include <exec/io.h> 
^include <exec/memory.h> 
#irclude <libraries/dos.h> 
^include <libraries/dosextens.h> 



extern struct FileHandle *0penO; 

main(argc.argv) 
int argc; 
char *argv[]; 

struct FileHandle *sp; 



ifC(s P =O pen (.. C oN:10/10/300/150/Window».MODE_0LDFILE))==0) 



Write(sp, "Deleting ",15); 

if ((DeleteFi leCargvd ]) )==0) { 
Vrite(sp,"Fi le Not Deleted" 20) : 
Close(sp); 
ExitO; 

> 



Close(sp); 



Files and Multiprocessing 

One new problem faced by Amiga programmers arises from the interaction or 

. Pr0CeSSeS ffl6S - ° D a 3 ^ le tasking system, only one 
program runs at a time. Any file that is open for reading or writing is the 
exclude property of that program. On the Amiga, you cL ha^e mly nrc- 

TZ^TZ^f aneously - md more than one ^SZS ! 

same file. Under certam circumstances, this can cause problems 

and Zltl^ COmm ° n P o° bIem areaS COncerns mea that are accessed 
and updated by two processes. Consider process A: it opens file FileA to do 

2 at °Tl a T S ° me , VaIue m the me * to be read, changed, and then 

jSTJ^tZ 3 T l0Cat r- At the same time P rocess B also opens 
FleA also to do an update on the same data value. What can happen? One' 
disastrous possibility is that process A will get the file and read the valued 

read ^ Z r, T t™ 8 *^ ^ the Value back to the file - P^ess B wfll 
read the old data. Meanwhile A will write back its new version of the data 

"18 
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lem-i s illustrated in Figured 38 the " Lost Update" prot. 

Figure 9-3. The Lost Update problem 




It ^^t^^Z^^T th - — t software failures, 
stances that is difficult to preouct When.v UP ° n 3 Set of ™um- 

mng in memory, doing differSTactior^T- than one P"*«» is run- 
which each process wl e xecute The som on STf* to ^ the ord -" 
other similar scheduhng difficulties !??n L ° St Update P robIe m and 

Processes will access the^ameffl You doTt ^ * Wbich ^ 
s ake out a daim for exdus . ve acceg ;°^ d ° this by allowing one process to 
file lock. ess w tne file, this is accomplished with the 

^d^mrlevd VSsittcefsCtt 1 ?^ ^ - d - 

system, the notion of a lock is a c ZZ Ue ' ° n a lar S e multi-user 

nations of access posJT^T^ 0 ^ ?' th man ^ level * or combT 
gaDOS supports a simpler 3°?^ ,0ck a Portion of a file. Ami 
to a given file-in this case any X^oc^ reqUeSt 3 shared a <*ess 

or it can ask for exclusive ZwSETL? 1 ^^ously access it- 
mechanism for this is the system calf g ^ ° ther Presses. The 

lock_value=Lock(fil e _ namefmode) 

where 

appear, i„ the dirSS " g ** C ° MaiM "» ™>°* of the fll. „ it 
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mode indicates the access mode for the lock: ACCESS READ creates 
a shared lock; ACCESS_WRITE grants exclusive access. 

nXk V f Ue ° f i! BdiC ff thG L0CW CaU failed - This does not necessar- 
dy indicate a problem. A failure here might indicate that some other process 
has put a lock on that file. process 

The Lost Update problem is solved by the use of file locks. Now Process 

Procts B hat ZZ^ ? ^ °P eration is «SS 

Process B has to wait to do its update, and that will be done not to the 

tEfual 11 : ^ t0 ^ 35 ^ ^ Pr ° CeSS A - Fi ^ e S^iSJS 
Figure 9-1. The Lost Update problem solved 




gemrlfuse: 13 3 C ° mpIementar y to that releases a file to 

UnLock(lock_value) 

Here Lock value is an identifier from a previously executed Lock<) function 
This function does not return a value. 

^Disk Update Functions 

One kind of update we might wish to perform on a file is to write into its 
comment fie d This field may be filled with any desired text Ld is m^lt to 
SSitfS"? M ° rmati ? ab ° Ut ^ ThiS COmment field 

ffi5&£££ command - Access t0 this part of the ffle is thr ^ h - 

boolean=Set Comment Cf i le_name,corament_f ield) 



m 
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where 

boolean indicates the success or failure of the call. 

file_name is a character string containing the name of a file as it 
appears m a directory. 

comment field is a pointer to a character string that contains the 
text of the comment. 

This comment field may be up to eighty characters long. 

Listing 9-4. use of SetCommentl ) to attach a 
comment to a file. 



•include <exec/types.h> 
•include <exec/nodes.h> 
•include <exec/lists.h> 
•include <exec/libraries.h> 
•include <exec/ports.h> 
•include <exec/interrupts.h> 
•include <exec/io.h> 
•include <exec/memory.h> 
•include <libraries/dos.h> 
•include <libraries/dosextens.h> 



main(argc,argv) 
int argc; 
char *argv[]; 
f 

struct FileLock *lock,*Lock() ; 
struct FileHandle *sp,*Input () ; 
char bufferC80],fnameC70]; 

sp=InputO; 

if <Uock=Lock(argvC1], ACCESS URITE))==0) < 
printf ("\nCan't open fileW); 
On Lock (Lock), • 
ExitO; 

> 



printf ("Comment: ") ; 
get_st ring(sp, buffer, 80); 



i f ( (SetComment (argv [1 ] , buf f er) )==0) 
switch(IoErrO) < 

case ERROR.COMMENT.TOO.BIG: printf ("Use a shorter comment^-) ; 

break; 

case ERROR_DEVICE_NOT_MOUNTED: printf ("Device not mountedW); 

break; 

case ERROR_WRITE_PROTECTED: 



FORMAT 
ZERO 
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Listing 9-4. (cont.l 



printf ("Diskette is write protected\n") ; 

break; 

case ERROR_NO_DISK: printfC'No diskette in the drive\n">; 

break; 



UnLockUock); 



get_st r i ng < f p, buffer, max len) 
struct FileHandle *fp; 
char *buffer; 
int max len; 
{ 

int len; 

Len=Read(f p, buffer, max L en) ; 
bu-ffer+=len+1 ; 
•buffers' \G"; 



■ 




Listing 9-4 contains a program that allows the user to set the comment 
field in a specific file. The file name is entered through the command line" 
arguments. The first thing we do with this file is try to put a lock on it; if thel 
lock fails, we exit with an error message. If we are successful in locking the: 
file, we prompt the user for the comment string; this is then used in a call to 
SetCommentf). If the call fails we invoke a new system function IoErr<) for a| 
more specific error message. Finally we call UnLockO to release the file. It is 
necessary to use the home grown input routine get_string(), because we i 
using the amiga.lib library and not Ic.lib. Common amenities like scanfl) | 
not available. 

IoErri) takes no parameters but returns an integer value that represent 
a global error message. This numeric value is associated with a particula|l 
error message. No global error message array— such as you find in the." 
standard library— is available. It is the responsibility of the application' 
create such an error message. Each error number is associated with a cor 
tion, using a Ifdefine statement. These statements are found in libraries/dos.l 
In our example program, we use a switch statement to perform this 
reporting function. 

Before you do anything to a disk by way of reading, writing, or updfl 
ing, it is important that you have some way of judging that disk's key para 
eters. Things like the size of the disk, its format, and other operatic 
parameters are necessary for certain kinds of access. This information 
stored in a special variable of type struct InfoData. The form of this : 
ture is: 
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struct InfoData { 

LONG id_NumSoftErrors, 
id_UnitNumber, 
id_DiskState, 
id_NumB locks, 
id_NunBlocksllsed, 
id_BytesPerBlock, 



T 



id_DiskType; ^ 
BSTR id.VolumeNode; TV T7> O 

LONG id InUse; «J *" 

>; ZARAGOZA 

where 

id_NumSoftErrors indicates the number of errors found on the disk 
id_UwtNumber indicates the unit of the disk. 
id_DiskState indicates the current condition of the disk 
id_NumBlocks counts the number of blocks on the disk 
id_NumBlocksU 8 ed is the number of blocks currently in use 
^BytesPerBlock shows the number of bytes contained in a block. 
id_D ls kType contains the type code. 

£-Vol«meNode points to a BCPL string containing the volume 

id_InUse is a flag value. 

The variable itself is filled by a call to: 

boolean=Info(lDck_value,info_variable) 
where 

boolean indicates the success or failure of the call. 
lock_value is a lock identifier from a call to Lock() 
invariable is a pointer to a variable of type struct InfoData 

disk or any file on iST£t^t^, 7*^ * hck - Value can to a 
foData structure "^formation is returned through the In- 
Listing 9-5. Use of Lock,, and Info() to accept the name of a 
^ V ° 1Ume and retu " bating parameters relati^ to it 



^include <exec/types.h> 
^include <exec/nodes.h> 
^include <exec/lists.h> 
^include <exec/libraries.h> 
^include <exec/ports.h> 
^include <exec/interrupts.h> 
^include <exec/io.h> 
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Listing 9-5. (cont.) 



^include <exec/memory .h> 
^include <libraries/dos.h> • 
#iiclude <li bran' es/dosext ens. h> 



main(argc,argv) 
i nt argc; 
char *argv[]; 
{ 

struct FileLock *lock,*Lock(); 

struct InfoData *i_data; 

if((lock=(struct FTleLock *) 

AllocMem(sizeof (struct Fi lelock) ,MEMF_CHIP|MEMF CLEAR))==0) 
Exit () ; 

iU(i_data=(struct InfoOata *) 
AllocMem(sizeof (struct InfoOata) ,MEMF CHIP|MEMF CLEAR))==0) 
ExitO; 

iK(Lock=Lock(argvC1] .ACCESS READ))==0) 
ExitO; 

if((lnfo(lock,i_data))==0) 
ExitO; 

printf ("Soft errors===>%ld\n", i_data->id_NumSoftErrors) ; 
printf ("Unit number===>Xld\n", i data->id Uni tNumber) ; 
printf ("Total blocks==>Zld\n", i2data->id NumBlocks);' 
printf ("Blocks in use=>%ld\n", i data->id~"NumBlocksUsed) : 
printf ("Blocks 

f ree===>%ld\n",i_data->id_NumBlocks-i_data->id_NumBlocksUsed); 
UnLock(lock); 



Listing 9-5 illustrates a program that accesses information about §»J 
specific disk. We accept a name through the command line arguments. Thit 
can be either a file, a directory, or simply a disk identifier— either dfnn ae% 
volume label. The program creates a lock pointer variable by a call to At 
locMemf). This is desirable because AmigaDOS requires variables that are. 
aligned with 32-bit values and using this function guarantees this ahgnmen 
Similarly, we create the variable i_data. Then an attempt is made to creatg 
lock using the entered file name. If the attempt succeeds, we call Mf 
passing it lock and i_data. If this, in turn, succeeds, we print out s 
interesting information about the disk. In operation, this program is similar 
to the CLI command Info.Cleanup and exit requires a call to UnLockf).* 
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Directory Maintenance 

^S^SZ^S the file S y Stem . They report 

files on the disk, and even r«£t wL^T • ^ aboUt the ^dividual 
comment field. AmigaDOS offers a vaTfv T mf ° rmation through the file 
very important software object 7 ° f SySt6m CaUs to deal ^h this 

The toS^S^^S^J^ FiIeInf °Block structure. 

. through variables 35 tC SSSS? ab ° Ut fUeS ^ Rectories 

tant parameter: ^ * structure contains a field for every impor- 

struct FilelnfoBlock { 
LONG fib_Diskey, 
rytp ^'b-DirEntryType; 
flln lb - Fl LeNa me[108]; 
LONG fib.EntryType, 
fib.Size, 

fib.NumBlocks; ~\ '( S T'l MAT 

struct DateStamp fib Date . 

> ; Char fib:CommentC116]; E R O 

where ZARAGOZ A 

fib_DirEntryType indicates the type of entry- 
-a value < 0 indicates a file; 
-a value > 0, a directory 

dlVcfory^ 6 " * ^ the name of a file or 

fib_Protection contains the protection code 
f.b_Size contains the number of bytes in the file 
f.b_Nu m Blocks reports on the number of blocks in the file. 
fib_Date is the date last changed. 
fib_Comment is the comment field 

fib_Diskey and fib_Ent ry Type are not for user applications. 
tuTn 3 Shi Z^^?*^ T - d *° Actions, which in 
To gather information about a file or directory, you can call: 

boolean=Examine(lock_value,fblock_ptr) 
where 

boolean indicates the success or failure of the call 

lock value is a lock identifier from a previous call to Lock( ) 

fblock_ptr ,s a pointer to a variable of type FilelnfoBlock ' 
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This M s the specified FilelnfoBlock variable with the current values for the 
Me, or the directory associated with the lock value. Listing 9-6 indicates how 
function can be used to make a report. The program accepts the name of 

FfJnfoBlock variable. /U/ocMem is used to ensure the proper memory word 
ahgnment. An attempt is made to create a lock for this object-ACCESS 
READ is acceptable because we are not doing an update, only getting infor" 
mation. A call to Examined fills the variable and then display some ^ inters - 
ing values on the screen. UnLockf) completes the program. 

Listing 9-6. Use of Lock!) and ExamineO to accept the name 
of a file or directory and display interesting information 
about it. 



^include <exec/types.h> 
^include <exec/nodes.h> 
^include <exec/lists.h> 
/(include <exec/libraries.h> 
^include <exec/ports.h> 
#include <exec/interrupts.h> 
^include <exec/io.h> 
#in:lude <exec/memory.h> 
^include <libraries/dos.h> 
^include <l i brari es/dosextens . h> 



main(argc,argv) 
int argc; 
char *argv[]; 
t 

struct FUeLock *lock,*lock () ; 
struct FilelnfoBlock *f_info; 

if <(lock=(struct FileLock *) 
MlocMenKsizeof (struct Fi leLock) ,MEMF_CHIP|MEMF_CLEAR))==0) 

if<(f_info=(struct FilelnfoBlock *) 
AllocMemCsizeof (struct Fi lelnfoBlock) ,MEMF_CHIP|MEMF_CLEAR»==0) 

ifC(Lock=Lock(argv[1], ACCESS READ))==0) 
ExitO; 




if C(Examine(lock,f info))==0) 
ExitO; 



if (f_info->f ib_Di rEntryType<0) 

printf ("Type====>Fi leW); 
elss 

srintf ("Type====>Directory\n"); 
printf ("Nan,e====>j;s\n",f_info->fib FileName); 
printf ("Si ze====>%ld\n",f info->fib Size)- 



Listing 9-6. ( con t.) 
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printf("Blocks==>Xld\n" f 
UnLock(lock); 

> 



ta » l ""=E»»«xt<l.ck.». lu( , fMotl ,_ ot| . ) 

The 

^C^c^ This system 

used in conjunction with Examine/) to ft dlrector y- ExNextf) is 

me SGt 0f P^dures yields tK^?* & ^ f ° U ™- 

I- Use ExamineO to gather information about the directorv 
2. Use repeated calls to ExNextt) t n „ > a <nr8C w»7- 

the directory. to get data on the subsequent files in 

^^S^^^^^ exe T ExNext > untiI * 

that the current condition ^iT^lTT^^ ^ to ^rfj verifies 
error. This algorithm is illustrated in iZZ^Tn^^ n <* a true 
Program 9-6, except that here w* h ? , 1118 P ro S rar n is similar to 
returns O^he 1 P J TncUon h Jh ^ •°° P that C ° Dti — -td 
make the program flow more structured mP ° rted t0 3 to 

- 



•include <exec/ty P es.h> 
•include <exec/nodes.h> 
•include <exec/lists.h> 
•include <exec/libraries.h> 
•include <exec/ports.h> 
•include <exec/interrupts.h> 
•include <exec/io.h> 
•include <exec/ mem0 ry.h> 
•include <libraries/dos.h> 
•include <libraries/dosextens.h> 




367 



'rogramming with Disk Files 



Listing 9-7. (cont.) 



main(argc,argv) 
int argc; 
char *argv[] ; 
{ 

struct FileLock *lock,*LockO ; 
struct Fi lelnfoBlock *f_info; 



if (dock=(struct FileLock *) 

AllocMem(sizeof (struct Fi leLock) ,MEMF_CHIP|MEMF_CLEAR))==0) 
ExitO; 

ifC<f info=(struct Fi LelnfoBlock *) 

AllocMem(sizeof (struct Fi lelnfoBlock) ,MEMF_CHIP | MEMF_CLEAR) )==0) 
ExitO; 

if((lock=Lock(argvC1],ACCESS_READ))==0) 
ExitO; 

if<(Exainine(lock,f_info))==0) 
ExitO; 

spi ll_the_beans(f_info); 

while ((ExNext(lock,f_info)) '=0) 
spi ll_the_beans(f_info) ; 

i f ( [oErr O==ERR0R_N0_M0RE_ENTRIES) 

printf ("\nEnd of di rectory===================\n") ; 

else 

printf ("\nError reading di rectory============\n"> ; 



UnLock(lock) ; 

) 

spi ll_the_beans(info) 
struct FilelnfoBlock *info; 
{ 

printf ("\n\nName====>%s\n",info->fib_Fi leName) ; 
printf ("Si ze====>Xld\n", i nf o->f ib_Si ze) ; 
printf ("Blocks==>%ld\n",info->fib_NumB locks); 
printf ("Note====>Xs\n",info->f ib.Comment); 

} 



AmigaDOS offers some important capabilities in addition to tho 
ready discussed— for example: 

lock_value=CreateDi r(di rect_name) 

This takes the name of a new directory and creates that directory on 
disk. A lock is automatically opened and returned by this function. A 
returned if the proposed name is the same as an existing directory. 
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Listing 9-8. Use of CreateDirQ to create a new directory. 



^include <exec/types . h> 
^include <exec/nodes . h> 
^include <exec/lists.h> 
^include <exec/libraries.h> 
^include <exec/ports.h> 
^include <exec/interrupts.h> 
^include <exec/io.h> 
^include <exec/memory . h> 
^include <l i brari es/dos . h> 
^include <libraries/dosextens.h> 



mai n (argc , argv) 
int argc; 
char *argv[]; 

struct FileLock *lock,*CreateOi rO ; 



if ((Lock=CreateDir(argvC1]))==n) 
ExitO; 

UnLock(lock) ; 

> 



Listing 9-8 contains a simple example. Listing 9-9 illustrates another system 

old=CurrentDir(new) 
Here old and new are lock values Thi<s fmirti™ „u 

directory to the directory associated wS ZT- ? P" the u CUrrent work *g 
tory value before the cha^^e is mlS ' ** CHir8nt 

AmigaDOS offers one last directory function: 

boolean=SetProtection(file.nam e> mask.value) 

Listing M Use of CreateDirf) and CurrentDirf) to create a 
nCW and °»ake it the current directory 



^include <exec/types . h> 
^include <exec/nodes . h> 
^include <exec/lists.h> 
^include <exec/libraries.h> 
^include <exec/ports.h> 
^include <exec/interrupts.h> 
^include <exec/io.h> 
^include <exec/meraory.h> 
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Listing 9-9. (cont.) 



#incLude <Libran'es/dos.h> 

#inc Lude <l i brari es/dosextens . h> 



main(argc,argv) 
int argc; 
char *argv[]; 
{ 

struct FileLock *lock,*last,*CreateDi r() ,*CurrentDi rO ; 



if ((Lock=CreateDir(argv[1]))==0) 
ExitO; 




if((Last=CurrentDir(Lock))==0) 1$ 

UnLock(lock); _ K O 

UnLock(last); ^ k * 



2, S 



This function sets the protection attributes of the file. Here file_name is a 
character string containing the file name, and Mask_value is a bit mask 
containing the protection code. Figure 9-5 indicates values for this mask. 
Read, write, execute, and delete modes are all set by this function. 

Figure 9-5. SetProtection( ) bit mask values 




No read access - 
No write access - 
No execute access - 
No deletion access - 



Device File Functions 



Our final example program deals not with disk files, but with device filesS 
input/output peripherals treated as if they were files. It is economical and 
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motivation for usmg the file metaphor rjlf WOrld; this *• the 

computer systems. However, 32fS^S£ tf? ***** aod m ° St oth <* 
particularly interactive dev ces sucTaf Z f peculiar to devices 

Fortunately, AmigaDOS recoSzes th P « ^ , keyboard md ^play screen 
that address them. eco ^ 1 ^ these peculiarities and supplies functions 

to a process when it starts 13J PU ' that 18 auto ™tically attached 

i le_handle_in=lnput () 
returns the file handle ot stdin. 
f i le _handle_out=OutPut() 

creating reason- 

lw»l«n*(tforcl»r(fii l . hlndl-|tli|r) 

* «^Si W .5&1^ 7 S^ Wai tForChari ). We declare 

to our standard input file. A call I to J*"** SGt Sp ^ uaJ 

and a subsequent call to Readf) puts the 22 ^ SCtS " P 0Ur mea «^ement 



# ncLude <exec/typ es . h > 

#inc ude <exec/nodes.h> 
^include <exec/Usts.h> 
^include <exec/libraries.h> 
include <exec/ports.h> 
include <exec/interrupts h> 
^include <exec/io.h> 
•include <exec/memory.h> 
•include <libraries/dos.h> 
•include <libraries/dosextens.h> 
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Listing 9-10. (cont.) 



tfdefine SEC 1000000 

mainO 
{ 

struct FileHandle *sp,*InputO; 

int len, result; 

char *buffer,*AUocMemO; 

if ((buffer=Al locMem(128,MEMF_CLEAR))==0) { 
printfO'Not enough memory for a buffer\n"); 
ExitO; 

> 

sp=Input() ; 



result=WaitForChar(sp,SEC); 

if (result==0) { 

printf ("\nTimeout\n") ; 
ExitO; 

> 

Len=Read(sp, buffer, 128); 
♦(buffer+aen+D^'NO 1 ; 

pri ntf ("==>Xs\n", buf f er) ; 



Summary 

In this chapter we have covered the AmigaDOS file management system. W§ 
have seen how files are defined and accessed. We have dealt with the notion o 
file locks and how they help manipulate files in a multiprocessing envii 
ment. 

We have discussed directories and the functions that report on their 
status and list their files. AmigaDOS also supplies functions that create new 
directories and change the current working directory. 

Finally, we have dealt with the difference between disk files and 
files. We have seen how to get access to the standard input and 
devices and use them in programs to create interesting input and out 
screens. We have explored the uses of the WaitForChari ) function and how 
can be used to time input requests. 
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AddBob! [) function to add Bobs to the 
trh.Ls linked list, 252 

AddGadgetf ) function to assign a 

system gadget to a window. 
66, 75 

AddPort( ) function to add ports to the 

system, 124 
AddSpritef ) function to add VSprite 

variables to the GELs linked 

list 239 

Advanced Research Projects Agency, 

o43 
Alerts, 95-97 

ALINK linker for the C compiler on 
the Amiga, 15 
files accepted by the, 20 
invoking the, 21-24 
passes of the, 20-21 

warning messages of the, 21 
Amiga 

creating sound on the, 271-74 

hardware architecture of the 4 
overview of the, 3-4 

programming environment of the 
9-27 

software architecture of the, 5-6 
AmigaDOS operating system, 115-44 
accessed through AStartUp obi 

24, 350 
calling the, 128-29 
console treated as a kind of file bv 
the, 104 ' 



AmigaDOS operating system-cont 
control of the file management and 
mult lp rocessing systems 
through, 117 

device file to activate the console 
device, 104 

for file management and 

multiprocessing support, 5, 12 
13, 349 

process definition, 127 
system functions for file 
management, 349-72 
amiga.lit - AmigaDOS functions library, 

AmigaDOS functions called by 
linking the source code to the 
129 

used to compile system functions 
350 

Amplitude of a sound wave, 268 
Analog quantities of sound translated 
to digital representations 
used by the computer, 268-69 
Area fill 0 f a graphic 

program using flood fill for the 
197-98 

program using outlining for the 
193-95 

program using RectFill( ) function 
with a pattern for the, 
200-201 
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Area fill of a graphic— cont 
program using ROM kernel 

graphics routines for the, 

191-93, 200-201, 202-5 , 
program using SetRastl ) function 

for the, 202-5 
system calls for the, 189-91 
Arealnfo structure to set up a buffer 

of information about a figure, 

191 

AreaMove( ) and AreaDraw( ) functions 
to fill polygons, 190-91, 193 

Arpabet of sounds with two or more 
standard alphabetic 
characters, 343-44 

Artificial speech, 3, 309-46 

program using the set_to_talk( ) 
function for unlimited number 
of spoken lines for, 320-22 
program using the speech 
synthesis subsystem to 
convert a single line to 
phonemes, then speak it, 
323-25 
program using the speech 
synthesis subsystem to 
convert an unlimited number 
of lines and speak them, 
326-28 

program using the translator 

library and narrator device to 

produce phonemes for, 317-19 
ASCII characters used with the 

console device, 104 
Audio device, 271-72 
accessing the, 274-97 
commands, 276-78 
controlling the, 278-97 
frequency in rendering speech 

sounds, 317 
opening the, 274-75 
program to finish executing a 

sound with the, 279-80 
program to specify the number of 

cycles for the, 277-78 
program to start a note and vary 

its loudness via messages sent 

to the, 290-92 
program to start a note and vary 

its period via messages sent 

to the, 287-89 
program to use a single channel of 

the, 284-86 



Audio device— cont 

program to use a square wave 

with the, 281-82, 284 
program to use a triangular wave 

with the, 282-84 
program to vary the loudness of a 

note using an array for the, 

292-95 

Audio system. See also Sound 

circuitry, Amiga's quality, 3 
four digital to analog converters 
for versatility in creating 
sounds with the, 4, 267, 271, 
311 

AUDIONAME global value, 275 
AutoRequest( ) function to create and 

install a boolean requester, 

93-95 



B 

Bit planes 

allocated for a screen, 52, 163 
Bobs images created through 

overlapping, 251-52 
Blitter device 

to move and combine data in 

memory, 4 
ROM kernel graphics commands 

that directly interact with the, 

182 

Blitter objects (Bobs), 236 

added and removed, from the 

GELs animation list, 252 
compared with functions of the 

VSprite, 251 
created with a struct Bob variab 

and VSprite variable, 251 
program illustrating the 

SAVEBACK feature, 257 
program to create a simple, 

253-56 

program to mix VSprites and 
260-64 

Bob variable, 251 

Book, organization of the, 6-7 

Boolean gadgets, 65, 71, 178, 181 1 

Boolean requester, 93 

Borders by Intuition graphics system; 
data structures for, 149-150 
program to create several link" 
153-55 
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Borders by Intuition graphics 
system— cont 

program to create simple, 151-53 

types of, 148-49 
Buffer 

for information about a figure 

created by Arealnfo structure, 
191 

to receive characters from a 
gadget, 73 



c 

^ C compiler, functions of the, 15-16 

^ C language 

M function calls, 6 

Q standard file definition in the, 

*Z 352-53 

*3 structure data types, 14-15 

^ system access through, 14-25 

q£ system prograinming, 6 

ClearMenuStrip( ) function, 81 
^ CLI command interpreter 
|S| calling processes from the, 129-31 
to start independent executing 
processes, 132 
Close! ) AmigaDOS function call 
to relinquish control over a file, 

353, 355 
to shut down the console, 104 
Close Gadget, 66, 69 
CloseDevice( ) system function to 

remove an audio device to a 
program, 271 
CloseLibrary( ) function to allow the 
operating system to reclaim 
memory used by the 
translator library, 313 
Color and the sprites, 219-220 
Color register(s) in the Amiga, 4 
addresses of, 52 
associated with VSprites, 238 
identifier and map for, 219-20 
each pixel assigned a value that 
points to a, 219 
Command file generated by ALINK, 
21-22 

Comments for a file, 360-62 
Compilation of individual function files 

then combined by the linker, 

62-63, 112 
Compiler. See C compiler and Lattice C 

compiler 



Composite gadget, 177 

Console device, 103-6 

Copper general purpose processor to 

control the graphics system, 4 
ROM kernel graphics commands 

that directly interact with the, 

182 

Coprocessors in the Amiga to handle 

specialized tasks, 4 
CreateDir( ) function to create a 

directory and a file lock, 

368- 70 

CreatePort( ) function to generate a 

new port, 124 
CreateProc( ) AmigaDOS function to 

return a process_id and 

start the process, 133, 134-43 
Cross-reference table of symbols and 

references in the file, 23 
CurrentDir( ) function to make a 

directory the current one, 

369- 70 

Custom (application specific) gadgets, 
70-76 

Customized screen(s) in Intuition, 
33-34, 39 

positioning the, 51-52 

program for creating a high- 
resolution window and a low- 
resolution window in two 
overlapping, 56-57 

program for creating a window in 
a, 48-51 

program for creating a window 
with custom colors in a, 52 

program for creating two 

overlapping high-resolution, 
53-56 

Cycles of a sound, 272, 273, 277-78 



D 

Data transfer directly from memory 

and diskette, 4 
Data types 

C language structure, 14-15 
specialized Amiga, 25-26 
structure, 70 
DateStamp( ) AmigaDOS system call, 
129 

Datestamp structure, 128 
Delay( ) AmigaDOS system call to add 
a delay in a program, 130 
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DeleteFile( ) function to delete a file or 

directory, 357-58 
Depth Arrangement Gadget, 219 
Depth Gadget, 66, 69 
Device drivers for the Amiga, 4 
Device file 

functions, 370-72 
identifiers, 350 
Digital representations of sound used 

by the Amiga, 268-69 
Digital to analog converters for 

versatility in creating sounds, 

4, 267, 271, 311 
Direct Memory Access (DMA) 

channels, eight special purpose, 

213 

coprocessors, 4 
Directory 

functions of the disk, 349-50 
maintenance, 365-70 
program to display information 
about a. 366-68 

Disk 

files, programming with, 349-72 
update functions, 360-64 
volume parameters, program to 

return the, 363-64 
Display Alert! ) function, 96 
Drag Gadget, 66, 69 
Draw! ) function to sketch a line in the 

color set by FgPen. 184, 188 
DrawBordert ) Intuition function to 

create a border, 148 
Drawlmaget ) Intuition function to 

generate a drawing, 148, 165 
Drawing pens defined in the RastPort 

structure, 183 
Drawing program, example of a, 

207-10 



E 

Error checking not complete in the 
example programs, 7-8, 
112-14 

Examine! ) function to display 

information about a file or 
directory. 366-68 

Example programs in this book, 7-8 

Executable file developed through the 
linker as the third stage in 
program development, 15 

Exec kernel. See ROM kernel graphics 
commands 

m 



Execute! ) AmigaDOS system call for 
simple multiprocessing, 
129-31 

Executive kernel operating 

environment, 5, 12, 13-14 
console device opened directly 

using the, 104 
message passing system of the, 

119-22, 123-27, 319 
ports and messages manipulated 

by the, 124 
software support for process 

creation supplied by, 127 
TrackDisk device handled by the, 

349 

ExNext! ) function to retrieve data 

about subsequent files, 367-68 



F 

FgPen function 

colors rendered by the, 183-84, 
189 

with PolyDraw to draw a polygon, 
186-88 

Filets) 

changing the name of a, 356-57 
comments for a, 360-62 
cursor, moving the, 356 
definition of a, -350-52 
deleting a. directory or a, 357-58 
device, functions of tie, 370-72 
explicit closing of each, 353 
handle, 351 
I/O, 352-56 

locks to share files among 

processes, 351, 359-60, 362, 
364, 368 
maintenance functions, 356-58 
multiprocessing and, 358-60 
program to display information 
about a, 366-68 
File management 

through AmigaDOS, 5, 12, 13, 349 
system, 349-50 
FileHandle structure, 353 
FilelnfoBlock structure, 365-66 
FileLock structure, 351-52 
Flags, IDCMP, 83, 98-103 
Flood! ) function to draw a figure in 
outline, then fill it, 195-98. 
Font, user-customized, 148 



Formants as frequencies to produce 

sounds of human speech, 311 
Frequency 

audio device, 317 

of a sound wave, 268, 272, 273-74 



G 

Gadget(s) 

application-specific (custom), 70-76 
controlling the interaction of 

individual, 72 
flags for, 67-68, 100-101 
graphics used with, 167-76 
library, 176-82 
program to create a window 

containing the system, 68-69 
program to develop access 

routines for, 178-81 
as specialized control objects in 

Intuition windows, 31 
system, 66-70 
types of, 65-66 
Gelslnfo structure variable, 236, 239, 

244, 248 

Get _ mouse! ) function to trap events 
within a window, 206- 10 

GetMsg! ) function 

to remove a process from a queue, 
136 

to retrieve a message from a port, 
125, 126 
Get_prop( ) function to create a 
proportional gadget, 181 
Get_string< ) function to create a three 

way gadget setup, 181 
Graphic Elements (GELs) subsystem 
displaying a list of the system 

objects of the, 239-40 
list, adding or removing Bobs on 
the, 252 

list, program example of multiple 
VSprites managed by one, 
248-51 

virtual sprites (VSprites) and 
blitter objects (Bobs) as the 
two basic units of the, 236 
Graphics 

commands, ROM kernel, 182-201 

gadgets used with, 167-76 

Intuition to prepare, 145-210 



Graphics— cont 

object movements controlled by 

sprite processors, 4 
as one of the features of the 

Amiga, 3 
output from Intuition, three types 

of, 148 

routines for displaying values and 

pictures, 103 
system controlled by the Copper 
processor, 4 
Graphics kernel functions for line 

drawing, 184-88 
Graphics primitives, creating an image 

directly using, 103 
"Guru Meditation" box, 96 

H 

Hardware 

accessing resources of the, 

traditional method of, 11-12 

architecture of the Amiga, 4 
High-resolution mode 

screens, 51, 53 

screens using very, 57 
Hold-and-modify (HAM) mode, 51 
Hot spot, 216-17 

Human speech, generation of, 311-12 
I 

Iconic interface, 134 

IDCMP (Direct Communications 

Message Ports) facility for 
communications, 83, 98-103 
flags of the, 98, 100-101 
program to communicate with an 
open window using, 102-3 
Images as output from Intuition 
graphics system, 148 
data structures for, 162-63 
definition of, 161 

program to create several, 165-67 

program to create simple, 163-65 
Info( ) function to return disk volume 

parameters, 363-64 
InfoData variable, 362-63 
Input 

device, 97 

event, 97-98 

stream, 97-98 
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Input( ) function to wait for a 

character to read from the 
keyboard, 371 
Input/output (i/o) 

from Boolean gadgets handled by 

the get_flag( ) function, 178 
operations stored in Intuition files, 
106-12 
Integer gadgets, 66, 75-76 
Interlace mode (interlaced screen), 51, 

57-61 
Intonation 

of punctuation marks by the 

narrator device, 345 
three kinds of, 345 
of vowels handled by the Narrator, 

344-45 
of words affected by the 
translate! ) function, 315 
IntuiMessage object, 98, 99-100 
IntuiText for graphics output from 
Intuition, 148 
data structures of the, 155-57 
measuring the length of a display 

in pixels with, 157 
program to create a simple 
structure with, 157-58 
program to create linked 
structures with, 158-61 
Intuition, 29-114 

drawing or preparing graphics 

with, 145-210 
file to open, 62-63 
library, building an, 106-12 
as the primary user interface, 5, 

12-13 
resources of, 31 
as a run-time library, 32 
IntuitionBase variable, 32 
I/O redirection 

Amiga's simplification of, 12 
in the terminal-like user interface 
of the Amiga, 3 
IOAudio structure, 273, 274-76, 278, 
284 

Ioerrt ) function to check for file errors, 
367-68 

ItemAddress! ) function to capture a 

Menultem structure's address, 
81 



L 

Lattice C compiler 

data element sizes for the, 26 

passes of the, 16-20 

phases of the, 16-19 

starting a compile with the, 16-17 

toggles for the, list of, 17-19 

two levels of input/output 

statements offered by the, 353 
Ic.lib standard library of routines, 24 
Libraries 

Intuition, 106-12 

linked to programs with the 

Amiga, 24 
loaded along with programs, not 

added to them, 32 
program to test functions of, 
111-12 

Lines, graphics kernel functions to 

draw, 184-88 
Linker. See ALINK linker for the C 

compiler on the Amiga 
LoadSegi ) AmigaDOS function to load 

object file into free memory 

locations, 132, 134-43 
Lock! ) function 

to display information about a file 

or directory, 366-68 
to return disk volume parameters, 

363-64 

"Lost Update"- problem, 358-60 
Loudness (amplitude) of a sound, 
272-74, 290-95 



M 

Makebarl ) function to draw a series of 

lines in one color, 184 
Map of the executable module, 22-23 
Mapleft and mapright bit maps, 301 
MC68000 (Motorola) processor in the 
Amiga, 4 

assembler for the, 5 
Memory 

Amiga's addressable, 4 

chip, 8 

co-resident programs loaded at tn 
other end of the computer's _ 
address system from the main 
program in, 119 

processes in, 119 
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resource freed by programmer's 
code after a library, screen, or 
window is no longer needed, 
112-13, 132-33, 226, 355 

tasking system to manage a 
process in, 127-28 

Menu(s) 

creating a, 81-92 

defining a, 77-81 

file containing the setup for, 210 

flags for a, 80-81, 101 

positioning a, 77-78 

program to create a, 84-86 

program to create, in two 

windows, 89-92 
program to create two, in one 

window 86-89 
setting up a. 76-92 
Menu strip, 83 

Menultem structure, initializing a 

78-79 
Message(s) 

facility. Narrator accessed using 

the, 316 
header, 127 

passing system between processes, 

119-22, 123-27. 319 
system to handle communications 

between an application and 

the audio device, 271 
Mode values of the set_params( ) 

function for varied speech 
parameters, 332-35 
ModifylDCMPI ) system function to 

prepare an open window to 

report 

on mouse and menu activity, 208 
Modular programming, 62-65 
Monaural sound possible with the 
Amiga, 271 

Mouse 

cursor, sprite 0 as the, 213, 214, 
216-19 

as the main access channel in 

Intuition, 31 
to select menu options, 77 
Mouth_rb structure to send messages 

to the Narrator without 
waiting for their completion, 325 
Move( ) graphics kernel function to 

reposition the drawing cursor, 
184, 188 



MoveSprite( ) function call to move a 
sprite on the screen, 226 

Multiprocessing 

design of applications affected by, 
3-4 

files and, 358-60 

operating system of the Amiga, 3 
Multitasking, 3, 13 

advantages of, 117-18 
artificial speech programs using, 
322-25 



N 

Narrator device to produce speech, 312 
accessed through the message 

facility, 316 
advantages of directly passing 

phonetic strings to the, 346 
Arpabet sounds used by the. 

343- 44 

background mode can be used to 
run processes of the, 315, 
325-26 

fields of the. 316-17 

intonation of vowels and 

punctuation marks by the, 

344- 45 

phonetic alphabet used by, 343 
program using the direct input of 

phonetics with the, 339-43 
program using pitch, mode, and 
sex values to the set_params 
function to expand the range 
of speech 
parameters for the, 322-35 

program using the set_params( ) 
function and sampling 
frequency for the, 335-43 
program using the set_params( ) 
function to set speech 
parameters for the, 328-31 
program using the translator 

library and the, 317-19 
varying the parameters sent to 
the, 328-46 
NewScreen structure to specify screen 

parameters, 48 
NewWindow structure to specify 

window parameters, 35-36, 
38-39 
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NewWindow structure to specify 
window parameters— cont 

IDCMPFlags field of the, 70 



o 

Object file 

compiled as the second stage in 

program development, 15 
£s an image of the memory when 
the program runs, 118 
Object modular disassemble (OMD) 

utility, 19-20 
OnMenu( ) and OffMenu( ) functions to 
turn menu items on and off 
without removing them, 81 
Open( ) AmigaDOS function call 

to open devices and disk files, 353 
to prepare a file for reading, 
354-55 

to set up and start the console, 
104 

OpenDevicel ) system function to 

attach an audio device to a 

program, 271, 284 
OpenLibraryl ) function to open the 

translator library, 313 
OpenWindow( ) function to create a 

window, 35-38 
Operating system(s) of the Amiga, 

three interacting, 3, 5, 12-14 



Pattern fill, 199-201 

Period of a sound wave, 272, 273-74, 

286, 289, 295-97 
Phonemes 

as linguistic sounds, 312 
streams of, 343 
Pitch values of the set_params( ) 

function for varied speech 
parameters, 332-35 
Pixels (picture elements) 

image to create a display by 
specifying the color 
information in, 161-62 
length of an IntuiText display 

measured in, 157 
measurements of the, 214 
transparent, 219 



Pixels (picture elements)— cont 

as the unit for measuring window 
positions, 35-36, 52 

Port(s) 

address, 124 

associated with each process, 120 
relationship of messages and, 

123-26 
reply, 122, 124 
Preprocessor command execution, 16 
PrintTextl ) Intuition function to 

generate a character display, 

Process 

child, 136, 138 

defined, 119 £. 
parent, 136. 138 _ 
program to create a compQ^.A »V 
139-41 

program to create a simple, 

134-36, 137-38 
program to create two, 141-43 
structure definition of an 
AmigaDOS, 127 
Process control, 115-44 
Program, example of a complete, 
113-14 

Programming environment, 9-27 
Intuition as the most difficult 

Amiga, 31 
software components of the, 11-14 
Programming style notes for example 

programs, 7-8, 112-14 
Proportional gadgets, 66, 170-76, 181 
Punctuation marks recognized by the 

narrator device, 345 
PutMsg( ) function to send an 

initialized message structure 

to a particular port, 125-26 



Q 



Queue for a process 

CreateProc( ) AmigaDOS function 

to insert a, 133 
removing a process from the, 136, 



R 

RastPort structure, 183-84, 199 
Read( ) function 
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Read( ) function— cont 

to read a character from the 

keyboard, 371-72 
to transfer bytes in the buffer 

array, 354-55 
RectFill( ) function to fill a figure with 

a pattern, 200-201 
RefreshGadgetl ) function, 75 
RemoveGadget( ) function to delete 

gadgets in an open window, 75 
RemIBob( ) system call to remove 

Bobs from the GELs system 

linked list, 252 
RemPort( ) function to remove ports 

from the system, 124 
RemVSpritel ) system call to remove 

virtual sprites from the GELs 

system linked list, 239 
Rename) ) function to change the name 

of an existing file, 356-57 
Reply Msg( ) system call to return the 

message structure to the port. 

125-26 

Requester for entering values, 92-95. 
101 

ROM kernel graphics commands. 
182-201 



s 

Sampling an analog waveform , 269-70 
frequency for, 317 
interval for, 273 
Sawtooth waveform, 273, 276-78 
Screen(s). See also Customized 
screen(s) in Intuition 
as the background for windows, 33 
high-resolution, 51, 53 
as the main visual object in 

Intuition, 31 
RastPort opened for each 

Intuition, 183 
support file stored as a separate 
function for Intuition, 63-64 
two kinds of Intuition, 33 
ScrollRaster( ) function, 205-7 
Sentences, Translate! ) function 

converts all strings to, 315 
SetAPenl ) function with Drawl ) 
function to produce 
multicolored lines, 184 
SetMenuStrip( ) function to associate a 
menu with a window, 81-82 



Set_params( ) function to set the 

parameters of speech, 328-39 

SetPointer( ) function to alter the 
shape of the mouse cursor, 
216-19 

SetProtection( ) bit mask values, 370 
SetRastl ) function to set the raster 

display to the pen color, 202-5 
Set _ to _ talk! ) function to allow 
unlimited spoken lines, 
program using the, 320-22 
Sex values of the set_params( ) 

function for varied speech 
parameters, 332-35 
SimpleSprite structure, 220-226 
Sin( ) function to fill an array to 

produce a sine curve, 273 
Size of compiled code, message 

indicating the, 19 
Sizing gadget, 66, 69, 70 
Software components of the 

programming environment, 
11-14 
Sound, 265-308 

Amiga produces stereo, 271 
channels, 298-307 
converted from analog quantities 
to digital representations used 
by the Amiga, 269-70 
creating, 267-69 
cycles of a, 272, 273, 277-78 
data representation, 272-74 
loudness of a, 272-74, 290-95 
multichannel, 297-307 
period of a, 272, 273-74, 286, 289, 
295-97 

program to alternate between and 

use two channels for a, 301-4 
program to alternate between 

channels with a, 298-301 
program to use all four channels 

to produce, 304-7 
system in the Amiga for creating, 

271-74 
volume of a, 286 
waves, 267-68 
Special Info structure for a 

proportional gadget, 172 
Speech synthesizer, Amiga's built-in. 

See Artificial speech 

Sprite(s) 

animating the, 211-64 
color and the, 219-20 
in custom screens, 51 
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Sprite(s)— cont 

defining a, 214-19 

image data arrays and loops to 

change the shape of, 233 
mouse cursor as a, 213, 214, 
216-19 

processors to control movements 

of graphics objects, 4 
program to allocate and move a 

multicolored, 222, 224-26 
program to allocate and move 

improved, 226-29 
program to allocate and move two, 

230-32 

program to change the shape of 
the, 233-36 

sbape of the, 214, 233-36 
Stack checking, disabling, 129 
Start-up routine, LStartUp.obj, 24 
Stress of a vowel, 344 
String gadgets. 65, 71, 73-74, 167-69 
Syllables. 312 

Symbol table, creation of the, lb 
System access, 14-25 
System clock, 4 

System gadgets built in to Intuition, 

66-70 . 
System software, access to the, 5-b 



Tasking system to manage a process 

in memory, 127-28 
Terminal-like interface of the Amiga, 3 
Timbre of a sound wave, 268-69 
Title bar 

for menus, 92 
for a screen. 52, 77-78 
for a window, 39 
Toggled menu items, 77 
TrackDisk device handled by the 

executive kernel, 349 
Translate! ) function to use the 

translator library, 313, 315 
Translator library 

to divide written words into 

constituent phonemes, 312-15 
to encode written words into 

phonemes, 312 
program to convert a character 
string into a phoneme string 
with the, 314-15 



Translator library— cont 

program using the narrator device 
and the, 317-19 
TTY-style interface, 350 

u 

UndoBuffer, 74 

UnloadSegl ) AmigaDOS function to 
remove a program from 
memory, 132-33, 134-43 
User interface 

two types of Amiga, 3 
Workbench Screen offers the 
standard Amiga, 33 



Variables, declaring and initializing 

structure, 113 , 
ViewPort, position of a sprite relative 

to a, 223, 226 
Virtual Sprites (VSprites) software 

sprites of the GELs 

subsystem, 236-39 
library file of animation support 

routines for, 243-44 
program to cause a single VSprite 

to bounce back and forth, 

240-43 

program to create and manipula 

two, 248-51 
program to make changes to a 
VSprite, 244-47 
Voltages that drive the Amiga's 

speakers, 272-73 
VSprite variables, 237-39, 251 



w 

WaitForCharl ) function to set up a 

measurement, 371-72 
WaitPortl ) function to put the current 
task to sleep until a signal 
reaches its port, 125-26, 136 
WaitTOFI ) command with a ~ 
MoveSpritet ) function call to 
move a sprite, 226, 243 
Window(s) 

colors applied in a, 39 
default settings for a, 39-4U 
defining a, 34-48 
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Window(s)— cont 

each program has a virtual 

terminal of its own in its, 

32-33 
flags for a, 101 
to handle input, output, and 

gadgets in Intuition, 31 
positioning the, 39 
program for creating overlapping, 

40-42 

program for opening a borderless, 
43-45 

program for opening a simple, 
36-40 

program for opening multiple 
windows of different colors, 
45-47 



Window(s)— cont 

RastPort opened for each 

Intuition, 183 
support file stored as a separate 

function for Intuition, 64-65 
title created for a, 39 
Windowing system of the Amiga, 3 
Workbench Screen, 33-34, 39, 132 
Workbench system utility to start a 

process, 132-48 
Wgets( ) function to initialize a 

parameter string, 108-9 
Wputs( ) function to place character 

strings in a window, 108-9 
Write( ) function to return the number 

of bytes placed on a file, 

354-55 
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